openapi: 3.0.1
info:
title: Gladly API
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](https://developer.gladly.com/rest/)
and implementing the [Lookup API](https://developer.gladly.com/rest/) 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](https://developer.gladly.com/rest/).
With these permissions, you can then go on to create the [API
Token(s)](https://developer.gladly.com/rest/) you need to access Gladly's
API [resources](https://developer.gladly.com/rest/).
## 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](https://developer.gladly.com/rest/) 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](https://developer.gladly.com/rest/)).
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
version: '1.0'
x-api-status-urls: false
x-konfig-ignore:
object-with-no-properties: true
potential-incorrect-type: true
servers:
- url: https://organization.gladly.com
tags:
- description: >
## Conversation
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 | Item Definition | Create | Read | Update
| Delete | Media |
|-------------------------------|----------------|--------|------|--------|--------|--------|
| Chat Message | A message sent/received via the
[Chat](https://help.gladly.com/docs/add-and-configure-chat-entry-points#)
channel | Yes | Yes | No | No | No |
| Conversation Status Change | Conversation status changed (e.g.: from
OPEN to WAITING, or OPEN to CLOSED) | Yes | Yes | Yes | No |
No |
| Custom Channel Message | A Message sent/received via a Custom
Channel integration | No | Yes | No | No | No |
| Customer Activity | Non-routable customer activity added to
customer timeline via API | Yes | Yes | No | Yes | No |
| Email | A message sent/received via the
[Email](https://help.gladly.com/docs/add-and-configure-email-entry-point)
channel | Yes | Yes | No | No | No |
| Facebook Messenger Message | A message sent/received via the
[Facebook
Messenger](https://help.gladly.com/docs/set-up-and-configure-facebook-messenger)
channel | Yes | Yes | No | No | No |
| Instagram Direct | A message sent/received via the
[Instagram](https://help.gladly.com/docs/set-up-and-configure-instagram-messaging)
channel | No | Yes | No | No | No |
| Note | An internal
[Note](https://help.gladly.com/docs/add-a-note-to-a-conversation) on the
Customer conversation | Yes | Yes | No | No | No |
| Phone Call | A [Phone
Call](https://help.gladly.com/docs/add-and-configure-voice-entry-points)
placed/received on Gladly | No | Yes | No | No | Yes |
| SMS Message | A message sent/received via the
[SMS](https://help.gladly.com/docs/add-and-configure-sms-entry-points)
channel | Yes | Yes | No | No | No |
| Task | A
[Task](https://help.gladly.com/docs/what-is-a-task) on a Customer's
profile | Yes | Yes | Yes | No | No |
| Topic Change | A
[Topic](https://help.gladly.com/docs/what-are-topics) added or removed on
a Conversation | Yes | Yes | No | Yes | No |
| Twitter (decommissioned as of 04/20/23) | A
message sent/received via the
[Twitter](https://help.gladly.com/docs/setup-and-configure-twitter-direct-messages)
channel | No | Yes | No | Yes | No |
| Voicemail | A Voicemail received | No | Yes |
No | No | Yes |
| WhatsApp | A message sent/received via the WhatsApp
channel | No | Yes | No | No | No |
### Chat Message
Content of messages sent between Gladly and customers through Gladly Chat.
### Conversation Status Change
Record of a change in the status of a conversation.
### Customer Activity
Information about activities customers participated in, for example,
emails they received, issues in another system, or customer satisfaction
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.

### Email
Content of emails sent between Gladly and customers.
### Facebook Messenger Message
Content of messages sent between Gladly and customers on Facebook
Messenger.
### Instagram Direct
Content of messages sent between Gladly and customers on Instagram Direct.
### Note
Content of the note recorded in Gladly.
### 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](https://developer.gladly.com/rest/).
### Task
Interacting with tasks through the conversations API is deprecated. Use
[Tasks API](https://developer.gladly.com/rest/) instead.
### Topic Change
Record of an agent adding or removing a topic from a conversation in
Gladly.
### Twitter (decommissioned as of 04/20/23)
Content of messages sent between Gladly and customers on Twitter.
### Voicemail
Information about voicemail left by customers in Gladly.
### WhatsApp
Content of messages sent between Gladly and customers on WhatsApp.
name: Conversations
- description: >
A task is a way to create and do internal follow-up work for a customer
within Gladly. Tasks have a due date, an assignee, a description of what
is needed for a customer, and can be commented on. These can be created
through the API to assign items to work within Gladly.

name: Tasks
- description: >
The collection of Message Automation APIs are used to facilitate
communication between a Customer via a Gladly channel and a 3rd party
Automation service, such as a chat bot. These APIs allow an Automation
service to interact with a Customer as well as close a Conversation with a
Customer or route a Customer to an Agent. Subscribe to the [Webhook
Event](https://developer.gladly.com/rest/) `AUTOMATION/MESSAGE_RECEIVED`
to receive inbound messages. **Note** The Message Automation APIs are
currently in a private beta and attachments are currently not supported.
Please contact your Customer Success Manager for access.
name: Message Automation
- description: >
Export API is a simple, comprehensive, file-based data export. You can
export the lifetime of your customers' conversations in Gladly to a
central data repository such as your data warehouse or data lake. You can
export all communications successfully delivered within a specified date
range. The export date range could be the past hour, the past 24 hours,
or a custom data range. Please note, for one-time exports covering a
period greater than six months, a service fee may apply.
Job results can be deleted once downloaded. Delete will remove all result
files along with the job metadata. Files older than 14 days are removed
from Gladly and jobs older than 14 days are not available from the API.
If you discover that you need the deleted files later, please contact
Gladly Support to regenerate them for you.
### SCHEDULING EXPORT JOBS
You can schedule a one-time or repeating - hourly or daily - data export
job. By default, each organization has a daily export job configured. To
schedule a one-time job or change the job frequency, please contact Gladly
Support.
name: Export
- description: >
A **Webhook** is a way to send notifications about Gladly events as a POST
request to the endpoint of your choice.
name: Webhooks
- description: >
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.
name: Agents
- description: >
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 Glad App
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](https://developer.mozilla.org/en-US/docs/Web/HTTP/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 Glad App Web widget

name: Answers
- description: >
A **Customer** in Gladly represents information about a customer of your
organization including their profile, contact information,
notes, and transactions.
Customers API allows you to add, update, and get customer profile data.
### Error Handling
Id, mobile phone number, and email address must be unique across customer
records. 409 errors returned will
include details on any conflicts, such as a field being taken.
Additionally, errors may be returned due to customer profiles being
merged. If a customer has been merged into
another, requests to get a customer by id will return 301 errors
specifying the new id of the customer,
and requests to update a customer by id will return 404 errors.
name: Customers
- description: >
Communications API enables you to programmatically send SMS messages to
your customers and receive messages from a
custom channel integration.
### Agent View

### Consumer View

name: Communications
- description: >
A **Report** in Gladly contains metrics that you need to run the contact
center. Reports API allows you to access Gladly's reports programatically.
name: Reports
- description: >
An **Inbox** receives customer communications in Gladly. The
communications route to the inbox according to channel and destination
endpoint configuration.
For example, all calls to a specific phone number or emails to a specific
address may go to an inbox.
name: Inboxes
- description: >
A **Team** represents a group of Agents. They may handle particular
**Inboxes** or types of work within Gladly.
name: Teams
- description: >
A **Topic** is a way of labeling a conversation in Gladly for specific
business purposes. For example, an agent may apply the topic "Return" to a
conversation where a customer returns merchandise.
Topics are used for reporting and to control various workflows.
Topics can be configured to have a nested hierarchy. For instance, the
topic "Return" could be a parent of "Size" and "Color" child topics. Visit
our [Help
Pages](https://help.gladly.com/docs/principles-of-hierarchical-topics) to
learn more about Hierarchical Topics.
name: Topics
- description: >
An **Event** is something that has happened in Gladly. The Events API
allows you to extract event details from the past 24 hours.
name: Events
- description: >
Freeform Topics allow you to associate granular data like Order Number to
a Conversation. This data can be accessed for analysis via APIs, Webhooks,
and AWS EventBridge. They are powered by custom attributes as you will see
throughout this API, the Conversations API, the Events API and events used
in Webhooks.
Note: These attributes are currently associated to the Conversation entity
only and are therefore different from customAttributes listed under the
Customer entity. See the Customer API for more information on Customer
custom attributes.
name: Freeform Topics
- description: >
An **Organization** contains metadata about your company that Gladly is
configured with.
name: Organization
- name: User Identity
- name: Payloads
- description: >
Gladly **webhooks** are an easy way to send notifications about Gladly
events and have them delivered to the endpoint of your choice, giving you
a streamlined method to trigger associated actions in external systems
that respond to events in Gladly.
Simply choose where to send notifications about events that you are
interested in (e.g. when a conversation is closed), and they’ll be
delivered to the endpoint of your choice.
Configure webhooks using the [Webhooks
API](https://developer.gladly.com/rest/) or the Webhooks Admin Page.
Users with API User permissions can configure webhooks by navigating to
Integrations > Webhooks.

## Securing Webhooks
We provide two methods for your web service to authenticate requests from
Gladly.
We recommend implementing at least one **authentication** option.
### Basic Authentication
For this method you will supply a username and password with the webhooks
`credentials` field. This will be sent with each request. You may
optionally supply a realm if needed.
### Header Based Token Authentication
For this method you will configure one or more HTTP headers with the
webhook's `headers` field. Gladly will send in each request to your web
service.
## Ping Event
Whenever you enable a webhook or update a webhook's URL, we'll send you a
special `PING` event.
Your web service is expected to respond with a 200 status code to this
event. If it does not respond or times out, the webhook create or update
will not succeed.
## Retry Policy
**Effective 6/28/23**
If your service responds to an event with a response code outside the 2XX
range or times out after 15 seconds, Gladly considers that delivery as
failed and will resend the request up to 4 times over an hour. After the
fourth attempt, we will deactivate the webhook and wil notify all API
Users in your organization's environment via email.
To reactivate the webhook, your team will first need to investigate the
issue and make the necessary changes for the webhook to start working
again. Once the issue is resolved, you will be able to re-activate the
webhook via the Settings > Webhooks page.
The following table shows the intervals between each retry attempt.
| Attempt | Retry interval |
| ------- | ------------------------ |
| 1 | 30 seconds |
| 2 | 5 minutes |
| 3 | 30 minutes |
| 4 | 1 hour |
## Logs
We provide the last 100 HTTP request logs for a webhook that occurred
during the past month. Logs can take up to 30 seconds to view and require
you to refresh the page.

Each log displays the status, event type and occurred at timestamp for a
given request. You can expand the log for more details about the request
and response.
For more information about webhook logs, please see our [Help
Documentation](https://connect.gladly.com/docs/help-documentation/article/reactivate-deactivated-webhooks/?highlight=webhook).
## Payloads
Gladly payloads are intentionally small: they contain only Gladly IDs and
event names rather than the object/data that has been modified or created
This helps Gladly webhooks perform more quickly when many events occur
throughout the day. This also assists with security, so if you
misconfigure a webhook, it does not send sensitive information to an
outside service.
To retrieve more information about the object in question, you may make an
additional Gladly API call to retrieve the Gladly object. For example, to
know more about conversationId whose status was updated, call the [GET
Conversation API](https://developer.gladly.com/rest/) or the [List Items
in Conversation API](https://developer.gladly.com/rest/).
## Available Events
Please see the [Help
Documentation](https://help.gladly.com/docs/reporting-concepts) for more
information about many of the events listed below.
| Event | Triggered by Gladly
when: |
| ------------------------------|
--------------------------------------------------------------|
| AGENT_AVAILABILITY/UPDATED | an Agent's availability is updated
|
| AGENT_STATUS/CHANGED_ACTIVE_REASON | an Agent's active reason is updated
|
| AGENT_STATUS/LOGGED_IN | an Agent logs in |
| AGENT_STATUS/LOGGED_OUT | an Agent logs out |
| AGENT_STATUS/RETURNED_FROM_AWAY | an Agent returns from away |
| AGENT_STATUS/WENT_AWAY | an Agent goes away |
| AUTOMATION/MESSAGE_RECEIVED | an Entry Point that has been
configured for Message Automation receives an inbound message |
| CONTACT/ENDED | a Contact is ended |
| CONTACT/FULFILLED | a Contact's SLA is fulfilled |
| CONTACT/HOLD_ENDED | a Contact's hold is ended |
| CONTACT/HOLD_STARTED | a Contact's hold is started |
| CONTACT/JOINED | an Agent joins a Contact |
| CONTACT/MESSAGE_RECEIVED | a Message is received |
| CONTACT/MESSAGE_SENT | a Message is sent |
| CONTACT/OFFER_ACCEPTED | a Contact's offer is accepted |
| CONTACT/OFFERED | a Contact is offered |
| CONTACT/OFFER_REJECTED | a Contact's offer is rejected |
| CONTACT/STARTED | a Contact is started |
| CONTACT/TRANSFERRED | a Contact is transferred |
| CONVERSATION/CLOSED | a Conversation is
closed |
| CONVERSATION/CREATED | a new Conversation is
created |
| CONVERSATION/CUSTOM_ATTRIBUTE_ADDED | a custom attribute has been added
to the conversation |
| CONVERSATION/CUSTOM_ATTRIBUTE_REMOVED | a custom attribute has been
removed from the conversation |
| CONVERSATION/NOTE_CREATED | a Note is added to a Conversation |
| CONVERSATION/REOPENED | a Conversation is reopened
| CONVERSATION/TOPIC_ADDED | a topic is added to a Conversation
|
| CONVERSATION/TOPIC_REMOVED | a Conversation's topic is removed |
| CONVERSATION_ASSIGNEE/UPDATED | a Conversation's assignee (inbox
and/or Agent) changes |
| CONVERSATION_STATUS/UPDATED | a Conversation changes statuses
(e.g.: from OPEN to CLOSED) |
| CUSTOM_CHANNEL/MESSAGE_SENT | an outbound message sent using a
Custom Channel |
| CUSTOMER/MERGED | a Customer Profile is merged with
another profile |
| CUSTOMER_PROFILE/CREATED | a Customer Profile is
created |
| CUSTOMER_PROFILE/DELETED | a Customer Profile is
deleted |
| CUSTOMER_PROFILE/MERGED | a Customer Profile is merged with
another profile |
| CUSTOMER_PROFILE/UPDATED | a Customer Profile is updated
(e.g.: name is updated) |
| EXPORT_JOB/COMPLETED | a [data export
job](https://developer.gladly.com/rest/) is
completed |
| EXPORT_JOB/FAILED | a [data export
job](https://developer.gladly.com/rest/) fails to
complete |
| MESSAGE/RECEIVED | an inbound message other than a
phone call is received |
| PAYMENT_REQUEST/CREATED | a payment request is created |
| PAYMENT_REQUEST/STATUS_CHANGED | a payment request's status changes
|
| PAYMENT_REQUEST/VIEWED | a payment request is viewed by the
Customer |
| PING | a webhook is initially created to
verify serivce availability |
| TASK/ASSIGNEE_UPDATED | a task's assignee is updated |
| TASK/CLOSED | a task is closed |
| TASK/COMMENT_ADDED | a comment is added to a task |
| TASK/CONTENT_UPDATED | the content of a task is updated |
| TASK/CREATED | a task is created |
| TASK/DUE_DATE_UPDATED | the due date of a task is updated |
| TASK/FOLLOWER_ADDED | a follower is added to a task |
| TASK/FOLLOWER_REMOVED | a follower is removed from a task
| TASK/REOPENED | a closed task is reopened |
name: Summary
- description: >
**Customer Lookup** allows you to provide a web service to search and get
customer profile data and transactions.
To support Customer Lookup, your organization will deploy an adaptor
service (aka Lookup Adaptor) running on your network that implements the
Lookup API.
From there you can can connect the service to internal systems providing
customer and transaction data.

### Overview
Building a Lookup Adaptor will allow you to showcase extended customer
profile information and actions in Gladly. For example, you may extend the
customer profile in Gladly with loyalty points and lifetime value to
assist with VIP routing. You can also display historical orders in Gladly
to allow agents to view frequently used directly in Gladly without having
to go to another system. You can even extend Gladly with Actions so that
agents can cancel orders or award loyalty points directly in Gladly!
On a high-level, Gladly will perform a request to your Customer Lookup
integration(s) to retrieve extended information from your system(s) about
a Customer Profile in Gladly.
To ensure performance, Gladly recommends that your Customer Lookup
integration(s) be able to respond back to the Gladly POST request in < 5
seconds. Gladly will terminate the request in 15 seconds if it receives no
response from your integration(s). Please note that if one Customer Lookup
integration times out / responds with an error that Gladly will consider
this an error for all Customer Lookup integration(s).
### Sample code
Sample code for building a Customer Lookup integration can be found
[here](https://github.com/gladly/lookup-practice).
### Architecture, Setup, Authentication, Sample Requests and More
A detailed overview of Lookup Adaptor architecture, requests, resposnes
and more can be found
[here](https://help.gladly.com/developer/docs/lookup-adapter-introduction).
name: Customer Lookup
- description: >
As we evolve the Gladly API over time, changes will be either added to the
current version of the API (i.e. **[backwards compatible
changes](https://developer.gladly.com/rest/)**),
or result in a new version that you will need to integrate with afresh
(i.e. **[non-backwards compatible
changes](https://developer.gladly.com/rest/)**).
## URL Path Versioning
The various versions of the Gladly API will be differentiated via global
versioning, with the relevant version number reflected within the path
parameter of the URL:
https://organization.gladly.com/api/v{major-version-number}/{resource path}
## Backwards Compatible Changes
For the most part, changes to the API will be backwards compatible, such
as adding resources, additional fields to response objects,
new value types for enums, or expanding a validation constraint to be more
accepting.
Ensure your client can gracefully handle or ignore unfamiliar fields and
values so it continues to operate smoothly over the lifespan of an API
version.
## Non-Backwards Compatible Changes
Versions will be upleveled when a non-backwards compatible change occurs.
This should not happen often, but can occur in the case of:
- a field being removed from an object
- a resource path no longer being supported
- changing the type of a field
- adding a new required parameter for a resource
- constricting the validation parameters for a request
These will only occur when absolutely necessary and a summary of the
changes from version to version can be viewed in the release notes.
Previous versions will be supported for a period of time before being
removed after providing ample advanced notice.
name: Versioning
- description: >
Wherever possible, Gladly uses standard HTTP status codes to signal the
success or failure of a call.
Generally speaking, `2xx` statuses indicate success, `3xx` statuses
indicate the client must take further action such as redirection,
`4xx` statuses indicate an error with the input supplied by the client,
`5xx` statuses indicate an unexpected error from Gladly servers (these
will be rare cases).
## Common Status Codes
| HTTP Status | Description |
| ----------- | ------------------------------------------------- |
| 200 | Success with results in response body |
| 201 | Resource created |
| 204 | Success with empty response body |
| 301 | The resource location has moved |
| 400 | API usage error |
| 401 | Authentication not provided |
| 403 | User does not have persmission to access resource |
| 404 | Resource is not found |
| 429 | Rate limit reached |
## Programmatic Remediation
In the case of a `400` response, there will be a structured list of
`error` objects that will provide information to correct the error.
The error object will contain a `code` to describe the problem.
The most common codes are:
| Code | Description |
| ------------ | -------------------------------------- |
| blank | Presence error |
| invalid | Format error |
| moved | This resource is now located elsewhere |
| not_a_number | Value not numeric error |
| present | Absence error |
| taken | Uniqueness error |
| too_long | Exceeds permissible length error |
| wrong_length | Length is not equal to expected error |
Refer to the errors section of each endpoint for more information.
Example:
{"errors":[{"code":"blank","detail":"one of emailAddress, phoneNumber must be present"}]}
name: Error Handling
- description: >
In some data properties, HTML markup is supported for formatting rich
content to display within Gladly.
For security and readability, only a limited set of HTML tags and
attributes are allowed.
| Tags |
Attributes
|
| ------------------- |
-----------------------------------------------------------------------------------
|
| a | href,
target
|
| img | src, align, alt, height,
width |
| h1, h2, h3
|
|
| hr, br
|
|
| div |
style
|
| span, p
|
|
| font | size,
color
|
| strong, em, b, i, u
|
|
| ul, ol |
type
|
| li | type,
value
|
| dl, dt, dd
|
|
| table
|
|
| tbody, tfoot | align,
valign
|
| col, colgroup | align, valign, height, width,
span |
| thead, tr | align,
valign
|
| td, th | align, valign, style, abbr, colspan, rowspan,
headers, height, width, scope, nowrap |
| caption
|
|
The `style` attribute may use style properties: `border-left`, `margin`,
`padding-left`, `text-align`, `background-color`.
name: Rich Content
- description: >
We are continuously expanding Gladly's integration capabilities. To get
early access to any of the following features, please contact Gladly
Support.
## New Integrations
Create customer service experiences that fit your business and delight
your customers. We continue to build integrations with applications that
your teams already rely on today. Customer satisfaction, quality
assurance, workforce management, email marketing, and order management are
application categories we're focusing on next. For the list of available
integrations, see our [Integrations
Library](https://www.gladly.com/integrations/).
## New APIs
If you can't wait for native integrations mentioned above, you can
integrate your apps with Gladly using a growing list of APIs and webhook
events. Sign up for our [release
notes](https://gladly.com/product-release) to be notified of new
developments.
name: Launching Soon
- description: "The number of requests for an **[organization](https://developer.gladly.com/rest/)** is rate limited for all APIs to ensure that adequate resources are available for all customers.\n\nGladly has two types of API rate limits:\n\n### Request Limit\nRequest limits are applied on a per-second basis and are implemented to protect against denial-of-service attacks. This ensures that adequate resources are available for all customers.\n\n### Concurrency Limit\nConcurrency limits are applied on the number of simultaneous requests to the endpoint. For example, a few long-lasting requests to an API endpoint simultaneously might exceed the concurrent rate limit for that endpoint.\n\n## Default Rate Limit\n\nOrganizations that send many requests in quick succession may see error responses that show up as status code\_**`429`**.\n>Individual APIs may have their own API Rate Limit and will be documented as such. Otherwise, the following default rate limits apply.\n\n| Method | Request Limit | Concurrency Limit |\n| ------------------- | -----------------------------------|----------------------------------|\n| GET | 10 Requests per second | Not Applicable |\n| POST | 10 Requests per second | Not Applicable |\n| PUT | 10 Requests per second | Not Applicable |\n| PATCH | 10 Requests per second | Not Applicable |\n| DELETE | 10 Requests per second | Not Applicable |\n\nWe may adjust limits to prevent abuse.\n\nIf you have questions about rate limited requests, please contact [Gladly Support](https://help.gladly.com/docs/contact-gladly-support).\n\n## Reporting API Rate Limit\n\nThe [Reports](https://developer.gladly.com/rest/) APIs have slightly different default rate limits than other APIs.\n\n| Method | Request Limit | Concurrency Limit |\n| ------------------- | -----------------------------------|----------------------------------|\n| POST | 10 Requests per minute | 2 concurrent requests at a time across the entire organization |\n\n## Handling Rate Limit\n\nThe Gladly API response headers include the organization's current rate limit and the number of requests remaining in the current second.\nThe remaining limit is calculated using the total number of requests received from all clients with your organization's API tokens.\n\n```json\n Ratelimit-Limit-Second\n Ratelimit-Remaining-Second\n```\n\nYou can anticipate hitting the rate limit by checking these headers.\n\nOne technique for gracefully handling rate-limited requests is to watch for\_**`429`**\_status codes and implement a client-side retry mechanism with an exponential backoff schedule.\nWe’d also recommend building some randomness into the backoff schedule to avoid a\_**[thundering herd effect](https://en.wikipedia.org/wiki/Thundering_herd_problem)**.\n"
name: Rate Limit
paths:
/api/v1/communications/sms:
post:
tags:
- Communications
summary: Send SMS
operationId: Communications_sendSms
description: >
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 [Gladly
Support](https://help.gladly.com/implementation/docs/filing-a-support-issue)
with a P4 designation.
Please be aware that:
- 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.
- 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.
- 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).
requestBody:
description: SMS to send
content:
application/json:
schema:
$ref: '#/components/schemas/CommunicationsSendSmsRequest'
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:
$ref: '#/components/schemas/CommunicationsSendSmsResponse'
'400':
description: Invalid field(s) in request body
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
/api/v1/communications/custom-channels/{customChannelId}/messages:
post:
tags:
- Communications
summary: Receive Custom Channel messages
operationId: Communications_receiveCustomChannelMessages
description: >
Custom Channels allows for building custom channel integration with
Gladly. This functionality is deactivated
by default.
**Note that the intended use case for custom channels is any non Gladly
messaging based supported channel.**
Please contact [Gladly Support](https://gladly.com/support) if you would
like to activate this API and believe you have a valid use case.
To receive a Custom Channel message, you must first create a Custom
Channel and a Custom Channel Entry Point in Gladly Settings -> Custom
Channels page. This API will accept messages from the channel
integration and process them similarly to built-in messaging channels.
parameters:
- description: >
The ID of the Custom Channel. To find the Custom Channel ID, you
must open the overflow menu of a
Custom Channel Entry Point and select the "View Integration Data"
option.
in: path
name: customChannelId
schema:
type: string
required: true
requestBody:
description: Custom Channel message
content:
application/json:
schema:
$ref: >-
#/components/schemas/CommunicationsReceiveCustomChannelMessagesRequest
required: true
responses:
'201':
description: |
Message received
headers:
Location:
schema:
description: >
The relative location of the created item that represents the
received message.
type: string
example: /api/v1/conversation-items/OOrlNMXeS72gs_WEX2TtMg
'400':
description: |
Invalid fields(s) in the request body
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
/api/v1/communications/custom-channels/{customChannelId}/messages/{messageId}/status:
put:
tags:
- Communications
summary: Update message status
operationId: Communications_updateMessageStatus
description: >
Update message status of Custom Channel messages sent from agents. This
allow a Custom Channel integration
to set message status to indicate to an Agent that the message has been
delivered.
parameters:
- description: >
The ID of the Custom Channel. To find the Custom Channel ID, you
must open the overflow menu of a
Custom Channel Entry Point and select the "View Integration Data"
option.
in: path
name: customChannelId
schema:
type: string
required: true
- description: |
The id of message updated
in: path
name: messageId
schema:
type: string
required: true
requestBody:
description: Custom Channel message status
content:
application/json:
schema:
$ref: '#/components/schemas/CommunicationsUpdateMessageStatusRequest'
required: true
responses:
'200':
description: |
Status updated
'400':
description: |
Invalid fields(s) in the request body
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'404':
description: |
Message with messageId not found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
/api/v1/conversations/{conversationId}:
get:
tags:
- Conversations
summary: Get conversation
operationId: Conversations_getMetadata
description: |
Get conversation metadata such as it's assignee, topics, inbox, etc.
parameters:
- description: Id of the conversation to get
in: path
name: conversationId
schema:
type: string
required: true
example: 9BcE2O0DQ2ynGHRmk9FeoA
responses:
'200':
description: Conversation metadata
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationsGetMetadataResponse'
example:
id: HXRqKC5GSV-jAlq0-sxYTA
topicIds:
- _DZTz4I0Qsq9YXxeXwufMg
- tYVmwhIVQe-2tflRIszQ3g
customAttributes:
- id: UCeBpdBVSNyaP54jhd8CZw
value: '1234556777'
- id: UCeBpdBVSNyaP54jhd8CZwX
value: '883399334403'
- id: cEBkE90eQHObfcsnrm60Tg
value: UPS
customerId: o2sg-TMTSD2rTwMuxzewbA
createdAt: '2016-01-02T00:10:00Z'
closedAt: '2016-01-03T08:10:00Z'
agentId: sHuXx-U3QqOmhvFusJGeBw
inboxId: E1nArq1uQAees_DogHB0MA
status: OPEN
'404':
description: A conversation with the given id does not exist
patch:
tags:
- Conversations
summary: Update conversation
operationId: Conversations_updateAssigneeStatus
description: |
Update conversation assignee, statusor both
parameters:
- description: Id of the conversation
in: path
name: conversationId
schema:
type: string
required: true
example: 9BcE2O0DQ2ynGHRmk9FeoA
requestBody:
description: JSON representation of conversation updates
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationsUpdateAssigneeStatusRequest'
example:
assignee:
inboxId: E1nArq1uQAees_DogHB0MA
agentId: sHuXx-U3QqOmhvFusJGeBw
status:
value: CLOSED
force: true
responses:
'204':
description: updated conversation
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
some required fields are blank:
value:
errors:
- attr: assignee.inboxId
code: blank
detail: '''inboxId'' cannot be blank when updating assignee'
- attr: status.value
code: blank
detail: '''value'' cannot be blank when updating status'
agent does not belong to inbox:
value:
errors:
- attr: assignee.agentId
code: invalid_state
detail: agent does not belong to inbox
reassigning closed conversation:
value:
errors:
- code: invalid_state
detail: closed conversation cannot be reassigned
topics required before closing conversation:
value:
errors:
- code: invalid_state
detail: topics are required before closing of conversation
customer waiting for response:
value:
errors:
- code: invalid_state
detail: >-
cannot close conversation, customer waiting for
response, set 'status.force' to true to override
'404':
description: A conversation with the given id does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
- code: not_exist
detail: conversation does not exist
/api/v1/conversation-items:
post:
tags:
- Conversations
summary: Create item
operationId: Conversations_createCustomerItem
description: >
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.
Any items created using this API will not be considered part of a
conversation, and are **non-routable** and **non-searchable** aside from
the mobile phone number or email address specified as part of the
payload.
requestBody:
description: Conversation Item to create
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationsCreateCustomerItemRequest'
examples:
Customer Activity:
value:
id: pOVVdzweSumI4bFxjlT8LA
customer:
emailAddress: michelle.smith@example.org
content:
title: Welcome to Gladly!
type: CUSTOMER_ACTIVITY
body: >-
At Gladly we set out to reinvent customer service. Why?
Because 21st century consumers are different. They are
from 18 to 80 years old, expect the brands they love to
recognize them, and to be able to communicate with your
agents over all channels – all the time.
activityType: EMAIL
sourceName: HubSpot
link:
url: https://www.gladly.com/product/
text: View Details
required: true
responses:
'200':
description: The created item
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationsCreateCustomerItemResponse'
'400':
description: Invalid field(s) in request body
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'409':
description: Specified id is in use
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
- attr: newConversationItems
code: taken
detail: conversation item already exists
/api/v1/conversation-items/{itemId}:
get:
tags:
- Conversations
summary: Get item
operationId: Conversations_getItem
description: |
Returns the conversation item with the provided id.
parameters:
- description: |
id of the conversation item
in: path
name: itemId
schema:
type: string
example: pOVVdzweSumI4bFxjlT8LA
required: true
responses:
'200':
description: conversation item
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationsGetItemResponse'
'400':
description: An item exists but is not supported by the API
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
- code: invalid
detail: >-
Conversation item with id [pOVVdzweSumI4bFxjlT8LA] exists
but is not supported by the API.
'404':
description: An item with the given id could not be found
delete:
tags:
- Conversations
summary: Delete item
operationId: Conversations_deleteItem
description: >
To delete an item.
Please note only items of type **CUSTOMER_ACTIVITY** may be deleted by
this API.
parameters:
- description: |
Id of the item to be deleted.
in: path
name: itemId
schema:
type: string
required: true
responses:
'204':
description: The item was deleted
'404':
description: An item with the given id could not be found
/api/v1/conversation-items/{itemId}/media/recording:
get:
tags:
- Conversations
summary: Get media
operationId: Conversations_getRecording
description: |
Returns the media file associated with the conversation item.
parameters:
- description: |
id of the conversation item
in: path
name: itemId
schema:
type: string
example: pOVVdzweSumI4bFxjlT8LA
required: true
responses:
'200':
description: The media file associated with the conversation item
content:
audio/mpeg:
schema:
$ref: '#/components/schemas/ConversationsGetRecordingResponse'
'404':
description: An item with the given id could not be found
/api/v1/customers/{customerId}/conversation-items:
post:
tags:
- Conversations
summary: Create item for customer
operationId: Conversations_createCustomerItem
description: >
To add items to a customer's timeline.
Any items created using this API will not be considered part of a
conversation, and are **non-routable** and **non-searchable** aside from
the mobile phone number or email address specified as part of the
payload.
parameters:
- description: >
Id of the customer associated with this item.
You can look up the id using the [Find
customers](index.html#tag/Customers) API.
in: path
name: customerId
schema:
type: string
required: true
requestBody:
description: Conversation Item to create
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationsCreateCustomerItemRequest1'
examples:
Customer Activity:
value:
content:
title: Welcome to Gladly!
type: CUSTOMER_ACTIVITY
body: >-
At Gladly we set out to reinvent customer service. Why?
Because 21st century consumers are different. They are
from 18 to 80 years old, expect the brands they love to
recognize them, and to be able to communicate with your
agents over all channels – all the time.
activityType: EMAIL
sourceName: HubSpot
link:
url: https://www.gladly.com/product/
text: View Details
responses:
'200':
description: The created item
content:
application/json:
schema:
$ref: >-
#/paths/~1api~1v1~1conversation-items/post/responses/200/content/application~1json/schema
'301':
description: >-
This customer id no longer exists, but has been moved because it has
been merged with another customer
headers:
Location:
description: Location of the new customer id to use
schema:
type: string
example: >-
https://example.gladly.com/api/v1/customers/TX6f82W4S_ayp11kP4dhrQ/conversation-items
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
- attr: customer id
code: moved
detail: >-
the customer id has changed from [wjotRA-fSU6feGCxdFwwNQ]
to [TX6f82W4S_ayp11kP4dhrQ]
meta:
old: wjotRA-fSU6feGCxdFwwNQ
new: TX6f82W4S_ayp11kP4dhrQ
'400':
description: Invalid field(s) in request body
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'404':
description: Customer with customerId does not exist
'409':
description: Specified id is in use
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
- attr: newConversationItems
code: taken
detail: conversation item already exists
/api/v1/customers/{customerId}/conversation-items/{itemId}:
delete:
tags:
- Conversations
summary: Delete item for customer
operationId: Conversations_deleteCustomerItem
description: >
To delete an item.
Please note only items of type **CUSTOMER_ACTIVITY** may be deleted by
this API.
parameters:
- description: >
Id of the customer associated with this item.
You can look up the id using the [Find
customers](index.html#tag/Customers) API.
in: path
name: customerId
schema:
type: string
required: true
- description: |
Id of the item to be deleted.
in: path
name: itemId
schema:
type: string
required: true
responses:
'204':
description: The item was deleted
'404':
description: >-
An item with the given id, for the given customer id, could not be
found
/api/v1/conversations/{conversationId}/items:
get:
tags:
- Conversations
summary: List items in conversation
operationId: Conversations_listItemsInConversation
description: >
Get the list of items in the timeline of a conversation.
The conversation represents a period of related interactions between a
customer and your organization.
The list is not paginated and will return at most 1000 items. The items
are returned in ascending order by timestamp.
The `Gladly-Limited-Data` header flag in the response will indicate if
the conversation has more items than returned.
parameters:
- description: Id of the conversation to get the timeline for
in: path
name: conversationId
schema:
type: string
required: true
example: 9BcE2O0DQ2ynGHRmk9FeoA
responses:
'200':
description: The items on the conversation timeline
content:
application/json:
schema:
$ref: >-
#/components/schemas/ConversationsListItemsInConversationResponse
example:
- id: ybP4szYCSy6LdV4DNwEd6g
conversationId: 9BcE2O0DQ2ynGHRmk9FeoA
customerId: OOrlNMXeS72gs_WEX2TtMg
timestamp: '2019-07-01T11:46:45.01Z'
initiator:
id: OOrlNMXeS72gs_WEX2TtMg
type: CUSTOMER
content:
type: CHAT_MESSAGE
sessionId: 5k04bYuTRGqyT6uoSQfWVA
content: >-
Hi! I know it's after hours but can someone help upgrade
my account?
- id: 9lQDrx-HTz-JMoP2T4CtZA
conversationId: 9BcE2O0DQ2ynGHRmk9FeoA
customerId: OOrlNMXeS72gs_WEX2TtMg
timestamp: '2019-07-02T06:30:12.07Z'
initiator:
id: WmeA3Y51Q5ayCAaZ1AotIA
type: AGENT
content:
type: EMAIL
from: amy.agent@company.com
to:
- martha.williams@gmail.com
subject: Account upgrade
content: >-
I would be happy to help you! We need a few details, so
please give us a call this morning.
- id: S6pMkJ78QMmkVf9qPP_SeQ
conversationId: 9BcE2O0DQ2ynGHRmk9FeoA
customerId: OOrlNMXeS72gs_WEX2TtMg
timestamp: '2019-07-02T08:05:00.10Z'
initiator:
id: OOrlNMXeS72gs_WEX2TtMgX
type: CUSTOMER
responder:
id: WmeA3Y51Q5ayCAaZ1AotIAX
type: AGENT
content:
type: PHONE_CALL
from: '+14153335555'
to: '+12149897676'
startedAt: '2019-07-02T08:05:00.10Z'
answeredAt: '2019-07-02T08:05:09.41Z'
completedAt: '2019-07-02T08:11:15.03Z'
recordingStatus: AVAILABLE
recordingURL: >-
/api/v1/conversation-items/S6pMkJ78QMmkVf9qPP_SeQ/media/recording
recordingDuration: '100'
- id: K0UGL3n6S4uPpvtMvItqHA
conversationId: 9BcE2O0DQ2ynGHRmk9FeoA
customerId: OOrlNMXeS72gs_WEX2TtMg
timestamp: '2019-07-02T08:12:55.870Z'
initiator:
id: WmeA3Y51Q5ayCAaZ1AotIAX
type: AGENT
content:
type: TOPIC_CHANGE
addedTopicIds:
- uu4t00vITaKQ3bVjU2UrGQ
- id: zwo9AtljSfaGjWb4Aq-aDQ
conversationId: WmeA3Y51Q5ayCAaZ1AotIA
customerId: o2sg-TMTSD2rTwMuxzewbA
timestamp: '2019-07-02T08:12:55.870Z'
initiator:
id": zGaHXjD4SR-moMR9LbULDA
type": AGENT
content:
type: CONVERSATION_STATUS_CHANGE
status: CLOSED
- id: azwo9AtljSfaGjWb4Aq-aDQ
conversationId: WmeA3Y51Q5ayCAaZ1AotIA
customerId: o2sg-TMTSD2rTwMuxzewbA
timestamp: '2019-07-02T08:12:55.870Z'
initiator:
id": zGaHXjD4SR-moMR9LbULDA
type": AGENT
content:
type: VOICEMAIL
startedAt: '2019-07-04T08:12:55.870Z'
recordingURL: >-
/api/v1/conversation-items/azwo9AtljSfaGjWb4Aq-aDQ/media/recording
recordingStatus: AVAILABLE
recordingDuration: 200
- id: DnaU23pZSIqOixATlII1vA
conversationId: HXRqKC5GSV-jAlq0-sxYTA
customerId: o2sg-TMTSD2rTwMuxzewbA
timestamp: '2019-07-04T23:42:57.780Z'
initiator:
type: AGENT
id: zGaHXjD4SR-moMR9LbULDA
content:
type: CONVERSATION_NOTE
body: >-
Customer has requested more information about our loyalty
program.
'404':
description: A conversation with the given id does not exist
/api/v1/conversations/{conversationId}/topics:
post:
tags:
- Conversations
summary: Add topic
operationId: Conversations_addTopicToList
description: >
Adds a list of topics to the conversation. If the topic being added
already exists on the conversation, that topic is ignored.
parameters:
- description: |
Id of the conversation.
in: path
name: conversationId
schema:
type: string
required: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationsAddTopicToListRequest'
examples:
Conversation Topic:
value:
topicIds:
- pOVVdzweSumI4bFxjlT8LA
- pOVVdzweSumI4bFxjlT8LB
required: true
responses:
'204':
description: The topic was added successfully
'400':
description: Invalid field(s) in request body
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'404':
description: A conversation with the given Id could not be found
/api/v1/conversations/{conversationId}/topics/{topicId}:
delete:
tags:
- Conversations
summary: Delete topic
operationId: Conversations_deleteTopic
description: |
Delete a topic from a conversation.
parameters:
- description: |
Id of the conversation.
in: path
name: conversationId
schema:
type: string
required: true
- description: |
Id of topic to be deleted from conversation.
in: path
name: topicId
schema:
type: string
required: true
responses:
'204':
description: The topic was deleted from the conversation successfully
'404':
description: A conversation with the given id could not be found
/api/v1/customer-history/{customerId}/conversations/{conversationId}/custom-attributes:
post:
tags:
- Conversations
summary: Add or Remove Freeform topic
operationId: Conversations_addFreeformTopics
description: >
Adds or removes a list of freeform topics to the conversation. If the
freeform topic being added already exists on the conversation, that
topic is ignored.
parameters:
- description: |
Id of the customer.
in: path
name: customerId
schema:
type: string
required: true
- description: |
Id of the conversation.
in: path
name: conversationId
schema:
type: string
required: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationsAddFreeformTopicsRequest'
examples:
Custom Attributes:
value:
add:
- key: ORDER_ID
value: ORD_3
- key: ORDER_ID
value: ORD_4
remove:
- key: ORDER_ID
value: ORD_1
- key: ORDER_ID
value: ORD_2
required: true
responses:
'204':
description: The freeform topic was added successfully
'400':
description: Invalid field(s) in request body
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrors'
'404':
description: A conversation with the given Id could not be found
/api/v1/conversations/{conversationId}/notes:
post:
tags:
- Conversations
summary: Add note
operationId: Conversations_addNoteToConversation
description: Adds note to an existing conversation.
parameters:
- description: |
Id of the conversation.
in: path
name: conversationId
schema:
type: string
required: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationsAddNoteToConversationRequest'
examples:
Conversation Note:
value:
content:
body: >-
Customer has requested more information about our loyalty
program.
responses:
'201':
description: The note was added successfully
headers:
Location:
schema:
description: Relative URL of the created note
example: >-
/api/v1/conversations/cHBetnP5QYiwg-rvfaVDAQ/notes/HVFDjpu1SCKJlDR7rRKkCQ
'400':
description: Invalid field(s) in request body
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'404':
description: A conversation with the given Id could not be found
/api/v1/conversations/{conversationId}/notes/{noteId}:
get:
tags:
- Conversations
summary: Get note
operationId: Conversations_getNote
description: |
Returns the note with the provided conversation and note id.
parameters:
- description: |
id of the conversation
in: path
name: conversationId
schema:
type: string
example: pOVVdzweSumI4bFxjlT8LA
required: true
- description: |
id of the note
in: path
name: noteId
schema:
type: string
example: aOVVdzweSumI4bFxjlT8LA
required: true
responses:
'200':
description: Conversation note
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationsGetNoteResponse'
'404':
description: An item with the given id could not be found
/api/v1/conversation-items/{itemId}/reply:
post:
tags:
- Conversations
summary: Reply to message
operationId: Conversations_sendResponse
description: Sends a response to a conversation item
parameters:
- description: |
id of the conversation item
in: path
name: itemId
schema:
type: string
example: pOVVdzweSumI4bFxjlT8LA
required: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationsSendResponseRequest'
examples:
Reply with email:
value:
content:
type: EMAIL
body:
Of course we can help with your issue!
bodyPlain: |-
Hi!
We can definitely help you with that!
Reply with chat message:
value:
content:
type: CHAT_MESSAGE
messageType: TEXT
body: Hi from chat!
Reply with chat quick reply:
value:
content:
type: CHAT_MESSAGE
messageType: QUICK_REPLY_REQUEST
body: Hi from chat! Please select an option!
messageData:
options:
- id: option-1
label: option one
- id: option-2
label: option two
Reply with facebook message:
value:
content:
type: FACEBOOK_MESSAGE
body: Hi from Facebook Messenger!
Reply with instagram direct message:
value:
content:
type: INSTAGRAM_DIRECT
body: Hi from Instagram Direct!
Reply with sms message:
value:
content:
type: SMS
body: Hi from SMS!
Reply with twitter direct message (decommissioned as of 04/20/2023):
value:
content:
type: TWITTER
body: Hi from Twitter Direct Messages!
Reply with whatsapp message:
value:
content:
type: WHATSAPP
body: Hi from WhatsApp!
responses:
'201':
description: >-
The reply was created successfully. Note that creation doesn't
guarantee delivery
headers:
Location:
schema:
description: Relative URL of the created message
example: /api/v1/conversation-items/HVFDjpu1SCKJlDR7rRKkCQ
'400':
description: Invalid field(s) in request body
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Closed conversation:
value:
errors:
- code: invalid
detail: you cannot reply to items in closed conversations
Empty type:
value:
errors:
- code: blank
attr: content.type
Wrong type:
value:
errors:
- code: invalid
detail: type [VOICEMAIL] is not supported
Body too long:
value:
errors:
- code: too_long
attr: content.body
detail: content.body cannot be larger than 2048 characters
Not a customer message:
value:
errors:
- code: invalid
detail: you can only reply to customer messages
'404':
description: A conversation item with the given id could not be found
/api/v1/conversation-items/{itemId}/redact:
post:
tags:
- Conversations
summary: Redact conversation item
operationId: Conversations_redactConversationItem
description: >
For supported items, the item's content will be removed but the item
will
remain in the conversation timeline. Supported types are Chat Message,
SMS Message, Email, Twitter (decommissioned as of 04/20/23, but can
still be redacted), WhatsApp, Voicemail, Phone Call.
parameters:
- description: |
id of the conversation item
in: path
name: itemId
schema:
type: string
example: pOVVdzweSumI4bFxjlT8LA
required: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationsRedactConversationItemRequest'
responses:
'201':
description: The redaction was successful.
headers:
Location:
schema:
description: Relative URL of the redacted item
example: /api/v1/conversation-items/HVFDjpu1SCKJlDR7rRKkCQ
'404':
description: A conversation item with the given id could not be found
/api/v1/message-automation/sessions/{sessionId}:
get:
tags:
- Message Automation
summary: Get Automation Session
operationId: MessageAutomation_getSession
description: Returns the automation session with the provided sessionId.
parameters:
- description: The id of the automation session.
in: path
name: sessionId
schema:
type: string
example: pOVVdzweSumI4bFxjlT8LA
required: true
responses:
'200':
description: Automation Session
content:
application/json:
schema:
$ref: '#/components/schemas/MessageAutomationGetSessionResponse'
'404':
description: An automation session with the given id does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
- code: not_exist
detail: entity does not exist
/api/v1/message-automation/sessions/{sessionId}/messages:
post:
tags:
- Message Automation
summary: Send Outbound Automation Message
operationId: MessageAutomation_outboundMessage
description: Returns the outbound automation message.
parameters:
- description: Id of the automation session.
in: path
name: sessionId
schema:
type: string
example: pOVVdzweSumI4bFxjlT8LA
required: true
requestBody:
description: Create an outbound message
content:
application/json:
schema:
$ref: '#/components/schemas/MessageAutomationOutboundMessageRequest'
example:
type: TEXT
content:
value: Your order is on the way!
required: true
responses:
'200':
description: The outbound automation message is created.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageAutomationOutboundMessageResponse'
'400':
description: Message has invalid type or content.
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
- attr: type
code: invalid
detail: invalid message type
'404':
description: >-
Message with the given messageId does not exist in the given
automation session.
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
- code: not_exist
detail: entity does not exist
get:
tags:
- Message Automation
summary: Get Automation Messages
operationId: MessageAutomation_getSessionMessages
description: >-
Returns all the messages within the automation session with the provided
sessionId.
parameters:
- description: |
Id of the automation session.
in: path
name: sessionId
schema:
type: string
example: pOVVdzweSumI4bFxjlT8LA
required: true
responses:
'200':
description: Automation session messages
content:
application/json:
schema:
$ref: >-
#/components/schemas/MessageAutomationGetSessionMessagesResponse
'404':
description: An automation session with the given id does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
- code: not_exist
detail: entity does not exist
/api/v1/message-automation/sessions/{sessionId}/messages/{messageId}:
get:
tags:
- Message Automation
summary: Get Automation Message
operationId: MessageAutomation_getMessage
description: >-
Returns the message with the provided messageId within the automation
session with the provided sessionId.
parameters:
- description: Id of the automation session.
in: path
name: sessionId
schema:
type: string
example: pOVVdzweSumI4bFxjlT8LA
required: true
- description: |
Id of the message.
in: path
name: messageId
schema:
type: string
example: 62723418e0374c00f31c4ca7
required: true
responses:
'200':
description: Automation session message
content:
application/json:
schema:
$ref: >-
#/paths/~1api~1v1~1message-automation~1sessions~1%7BsessionId%7D~1messages/post/responses/200/content/application~1json/schema
'404':
description: >-
Message with the given messageId does not exist in the given
automation session.
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
- code: not_exist
detail: entity does not exist
/api/v1/message-automation/sessions/{sessionId}/handoff:
post:
tags:
- Message Automation
summary: Agent Handoff
operationId: MessageAutomation_handoffSessionToAgent
description: >-
Handoff communication of the automation session, given sessionId, to an
agent. If successful, returns nothing.
parameters:
- description: Id of the automation session.
in: path
name: sessionId
schema:
type: string
example: pOVVdzweSumI4bFxjlT8LA
required: true
requestBody:
description: Handoff to agent.
content:
application/json:
schema:
$ref: >-
#/components/schemas/MessageAutomationHandoffSessionToAgentRequest
examples:
Message Content:
value:
description: Could not handle request. Hand off to agent.
required: true
responses:
'204':
description: The handoff is successful.
'400':
description: Failed to handoff to agent.
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
- code: not_exist
detail: entity does not exist
/api/v1/message-automation/sessions/{sessionId}/close:
post:
tags:
- Message Automation
summary: Close Automation Session
operationId: MessageAutomation_closeSession
description: >-
Closes the automation session for the given sessionId. Returns nothing
if successful.
parameters:
- description: Id of the automation session.
in: path
name: sessionId
schema:
type: string
example: pOVVdzweSumI4bFxjlT8LA
required: true
requestBody:
description: Close the automation session.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageAutomationCloseSessionRequest'
examples:
Message Content:
value:
description: Customer not responding. Close session.
required: true
responses:
'204':
description: Automation session was successfully closed.
'400':
description: Failed to close the given automation session.
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
- code: not_exist
detail: entity does not exist
/api/v1/tasks:
post:
tags:
- Tasks
summary: Create task
operationId: Tasks_customerTimeline
description: >
To add tasks to the timeline for a customer specified by identifying
information. If the customer doesn't exist, a new customer profile is
created.
requestBody:
description: Task to create
content:
application/json:
schema:
$ref: '#/components/schemas/TasksCustomerTimelineRequest'
responses:
'201':
description: task created
headers:
Location:
schema:
description: path to the created task
type: string
example: /api/v1/tasks/OOrlNMXeS72gs_WEX2TtMg
'400':
description: Invalid field(s) in request body
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
/api/v1/customers/{customerId}/tasks:
post:
tags:
- Tasks
summary: Create task for customer
operationId: Tasks_createCustomerTask
description: |
Add a task to an existing customer's conversation timeline
parameters:
- description: >
Id of the customer associated with the task to create.
You can look up the id using the [Find
customers](index.html#tag/Customers) API.
in: path
name: customerId
schema:
type: string
required: true
requestBody:
description: Create Task
content:
application/json:
schema:
$ref: '#/components/schemas/TasksCreateCustomerTaskRequest'
responses:
'201':
description: task created
headers:
Location:
schema:
description: path to the created task
type: string
example: /api/v1/tasks/OOrlNMXeS72gs_WEX2TtMg
'400':
description: Invalid field(s) in request body
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'404':
description: Customer with customerId does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrors'
'409':
description: Specified id is in use
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
- attr: newConversationItems
code: taken
detail: task already exists
get:
tags:
- Tasks
summary: List tasks
operationId: Tasks_getCustomerTasks
description: >
Fetch all tasks for a customer.
The list is not paginated and will return at most 2000 tasks. The tasks
are returned in descending order by timestamp.
The `Gladly-Limited-Data` header flag in the response will indicate if
the customer has more tasks than returned.
To see and act on any newly created tasks, webhooks can be used to
listen for task related events.
Tasks older than the limit can be viewed using the Task Export.
parameters:
- description: |
Id of the customer whose tasks you'd like to view.
in: path
name: customerId
schema:
type: string
required: true
- description: |
Fetch tasks with the provided status.
in: query
name: status
required: false
schema:
type: string
enum:
- OPEN
- CLOSED
responses:
'200':
description: Array of tasks
content:
application/json:
schema:
$ref: '#/components/schemas/TasksGetCustomerTasksResponse'
'400':
description: Invalid input
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'404':
description: A customer with the given id does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrors'
/api/v1/tasks/{taskId}:
patch:
tags:
- Tasks
summary: Update task
operationId: Tasks_updateTask
description: |
Update an existing task
parameters:
- description: |
Id of the task that is to be updated
in: path
name: taskId
schema:
type: string
required: true
requestBody:
description: Task properties to create
content:
application/json:
schema:
$ref: '#/components/schemas/TasksUpdateTaskRequest'
responses:
'204':
description: The task was created task
'400':
description: Invalid field(s) in request body
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'404':
description: Task with taskId does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrors'
get:
tags:
- Tasks
summary: Get task
operationId: Tasks_getTask
description: |
Get task
parameters:
- description: |
Id of the task requested
in: path
name: taskId
schema:
type: string
required: true
responses:
'200':
description: Returns requested task
content:
application/json:
schema:
$ref: '#/components/schemas/TasksGetTaskResponse'
'404':
description: Given task id does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrors'
/api/v1/tasks/{taskId}/comments:
post:
tags:
- Tasks
summary: |
Add task comment
operationId: Tasks_addTaskComment
description: >
Create a comment on a task. Note that you can’t create comments on
closed tasks.

parameters:
- description: |
Id of the task that will be commented on.
in: path
name: taskId
schema:
type: string
required: true
requestBody:
description: Add comment to task
content:
application/json:
schema:
$ref: '#/components/schemas/TasksAddTaskCommentRequest'
responses:
'201':
description: comment added
headers:
Location:
schema:
description: path to the created task
type: string
example: /api/v1/tasks/OOrlNMXeS72gs_WEX2TtMg/comments/77323sf2fj2k
'400':
description: Invalid field(s) in request body
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'404':
description: Task with taskId does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrors'
get:
tags:
- Tasks
summary: Get task comments
operationId: Tasks_getTaskComments
description: >
The comments are returned in ascending order by createdAt timestamp. The
list is not paginated and will return at most 1000 task comments. The
`Gladly-Limited-Data` header flag in the response will indicate if the
task has more comments than returned.
To see and act on any newly created task comments, webhooks can be used
to listen to any task comment related events.
parameters:
- description: |
Id of the task comments are requested for.
in: path
name: taskId
schema:
type: string
required: true
responses:
'200':
description: All comments that belong to task
content:
application/json:
schema:
$ref: '#/components/schemas/TasksGetTaskCommentsResponse'
'404':
description: Task with taskId does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrors'
/api/v1/tasks/{taskId}/comments/{commentId}:
get:
tags:
- Tasks
summary: Get task comment
operationId: Tasks_getComment
description: |
Get task comment.
parameters:
- description: |
Task id
in: path
name: taskId
schema:
type: string
required: true
- description: |
Comment id
in: path
name: commentId
schema:
type: string
required: true
responses:
'200':
description: Returns task comment
content:
application/json:
schema:
$ref: '#/components/schemas/TasksGetCommentResponse'
'404':
description: Comment with commentId does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrors'
/api/v1/custom-attributes/:customAttributeId:
get:
tags:
- Freeform Topics
summary: Get custom attribute
operationId: FreeformTopics_getAttribute
description: >
Returns a custom attribute that matches the provided custom attribute
id.
parameters:
- description: |
id of the custom attribute
name: customAttributeId
in: path
required: true
schema:
type: string
example: 1grfSzATQLa334VDLCWc4A
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/FreeformTopicsGetAttributeResponse'
'404':
description: Custom Attribute not found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
code: not_exist
detail: custom attribute 1grfSzATQLa334VDLCWc4A does not exist
/api/v1/customer-profiles:
post:
tags:
- Customers
summary: Create customer
operationId: Customers_createProfile
description: |
Create a new customer with the supplied profile data.
requestBody:
description: Customer record to add.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomersCreateProfileRequest'
example:
id: OOrlNMXeS72gs_WEX2TtMgX
name: Francis Avallone
address: 4303 Spring Forest Ln, Westlake Village, CA 91362-5605
emails:
- original: existing@francisavallone.com
phones:
- original: '+17192662837'
type: HOME
externalCustomerId: a21c1636-c622-48b7-bf6a-d9032645aa55
customAttributes:
albums: '6'
singles: '40'
responses:
'201':
description: customer created
headers:
Location:
schema:
description: location of the created customer
type: string
example: /api/v1/customer-profiles/OOrlNMXeS72gs_WEX2TtMg
'400':
description: error creating customer
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'409':
description: Specified id is in use or a uniqueness constraint failed
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
- attr: id
code: taken
detail: customer ID exists
get:
tags:
- Customers
summary: Find customers
operationId: Customers_findProfiles
description: >
Find customers by searching by choosing **one** of the following
identifiers as query parameters:
```
/api/v1/customer-profiles?phoneNumber=%2B14151234567
```
Max limit of 50 profiles returned, sorted by most recently updatedAt
date descending.
parameters:
- description: customer email address to search on.
name: email
in: query
schema:
type: string
example: customer@email.net
- description: >-
Customer ID in your system of record for Customer Profiles linked to
a Lookup Adaptor installed prior to 05/12/21. If Customer Profile is
linked to a Lookup Adaptor installed on or after 05/12/21, this
field is not searchable.
name: externalCustomerId
in: query
schema:
type: string
example: a21c1636-c622-48b7-bf6a-d9032645aa55
- description: >
Phone number in E.164 format. The value should be URL escaped where
`+` becomes `%2B`.
name: phoneNumber
in: query
schema:
type: string
example: '+16505551987'
responses:
'200':
description: found customers
content:
application/json:
schema:
$ref: '#/components/schemas/CustomersFindProfilesResponse'
'400':
description: error finding customers
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
/api/v1/customer-profiles/{customerId}:
parameters:
- description: id of the customer
name: customerId
in: path
required: true
schema:
type: string
example: OOrlNMXeS72gs_WEX2TtMg
get:
tags:
- Customers
summary: Get customer
operationId: Customers_getProfileById
description: >
Get a customer by unique id.
If a customer has been merged into another, an error will be returned
specifying the new id of the customer.
responses:
'200':
description: fetched customer
content:
application/json:
schema:
$ref: '#/components/schemas/CustomersGetProfileByIdResponse'
'301':
description: >-
customer id no longer exists and has been changed due to a merge
with another customer
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
- attr: customerId
code: moved
detail: customer id has changed
meta:
old: OOrlNMXeS72gs_WEX2TtMg
new: rVamfZHvQuORFnsk-3mNuw
'404':
description: customer not found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
code: not_exist
detail: customer profile [OOrlNMXeS72gs_WEX2TtMg] does not exist
patch:
tags:
- Customers
summary: Update customer
operationId: Customers_updateProfileById
description: >
Update a customer by unique id with the supplied JSON patch.
You may supply only the properties which you want to update or insert
into the profile.
When updating arrays, such as `phones` and `emails` you must provide the
entire list of values
since it is not possible to add or delete a single value.
If a customer has been merged into another, an error will be returned
specifying the new id of the customer.
requestBody:
description: JSON patch of customer profiles properties to insert or update.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomersUpdateProfileByIdRequest'
example:
name: Frankie Avalon
emails:
- original: existing@francisavallone.com
- original: new@frankieavalon.com
customAttributes:
albums: '7'
singles: '41'
responses:
'204':
description: updated customer
'400':
description: error updating customer
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'404':
description: customer not found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
/api/v1/user-identity-jwt:
post:
tags:
- User Identity
summary: Create a User Identity JWT
operationId: UserIdentity_generateJwt
description: >
Create a User Identity JWT for a customer. The JWT is used to
authenticate the customer with
[Glad App](https://developer.gladly.com/glad-app/). The JWT contains the
customer identity information.
requestBody:
description: Customer Identity Information
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserIdentityGenerateJwtRequest'
example:
identityType: EMAIL
identity: test@example.com
responses:
'200':
description: customer created
content:
application/json:
schema:
$ref: '#/components/schemas/UserIdentityGenerateJwtResponse'
'400':
description: error creating JWT
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
/api/v1/orgs/{orgId}/answers-search?q=search+terms:
get:
tags:
- Answers
summary: Search public answers
operationId: Answers_searchResults
description: |
Returns a list of answers that match the provided query string.
parameters:
- description: >
id of your organization
You can look up the ID using the [Get
organization](index.html#tag/Organization) API.
name: orgId
in: path
required: true
schema:
type: string
example: ihKsWxiZCDVtXg1iwVmT9Q
- description: search term
name: q
in: query
schema:
type: string
example: reset%20password
- description: language code
name: lng
in: query
schema:
type: string
example: en-us
- description: >-
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.
name: audienceId
in: query
schema:
type: string
example: en-us
responses:
'200':
description: found answers
content:
application/json:
schema:
$ref: '#/components/schemas/AnswersSearchResultsResponse'
/api/v1/orgs/{orgId}/answers?lng={lng}&audienceId={audienceId}:
get:
tags:
- Answers
summary: List public answers
operationId: Answers_listPublic
description: |
Returns the first 1000 public answers sorted alphabetically by name.
parameters:
- description: >
id of your organization
You can look up the ID using the [Get
organization](index.html#tag/Organization) API.
name: orgId
in: path
required: true
schema:
type: string
example: ihKsWxiZCDVtXg1iwVmT9Q
- description: |
Language of the answers returned
Defaults to `en-us`
name: lng
in: query
schema:
type: string
example: es-419
- description: >
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.
name: audienceId
in: query
schema:
type: string
example: ihKsWxiZCDVtXg1iwVmT9Q
responses:
'200':
description: answers
content:
application/json:
schema:
$ref: '#/components/schemas/AnswersListPublicResponse'
/api/v1/orgs/{orgId}/help-center/{helpCenterId}/answer-titles?lng={lng}&audienceId={audienceId}:
get:
tags:
- Answers
summary: List Help Center Answer Titles
operationId: Answers_listAnswerTitles
description: >
Returns an array of answers configured in Help Center sections with
their ID and name
parameters:
- description: >
id of your organization
You can look up the ID using the [Get
organization](index.html#tag/Organization) API.
name: orgId
in: path
required: true
schema:
type: string
example: ihKsWxiZCDVtXg1iwVmT9Q
- description: >
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
name: helpCenterId
in: path
required: true
schema:
type: string
example: ihKsWxiZCDVtXg1iwVmT9Q
- description: |
Language of the answers returned
Defaults to `en-us`
name: lng
in: query
schema:
type: string
example: es-419
- description: >
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.
name: audienceId
in: query
schema:
type: string
example: ihKsWxiZCDVtXg1iwVmT9Q
responses:
'200':
description: answers
content:
application/json:
schema:
$ref: '#/components/schemas/AnswersListAnswerTitlesResponse'
/api/v1/orgs/{orgId}/answers/{answerId}:
get:
tags:
- Answers
summary: Get public answer
operationId: Answers_getById
description: |
Returns the answer with the provided id.
parameters:
- description: >
id of your organization
You can look up the ID using the [Get
organization](index.html#tag/Organization) API.
name: orgId
in: path
required: true
schema:
type: string
example: ihKsWxiZCDVtXg1iwVmT9Q
- description: id of the answer
name: answerId
in: path
required: true
schema:
type: string
example: 1grfSzATQLa334VDLCWc4A
- description: language code
name: lng
in: query
schema:
type: string
example: en-us
responses:
'200':
description: answer
content:
application/json:
schema:
$ref: '#/components/schemas/AnswersGetByIdResponse'
/api/v1/agents:
get:
tags:
- Agents
summary: List Agents
operationId: Agents_list
description: |
Returns a list of agents.
responses:
'200':
description: Agents
content:
application/json:
schema:
$ref: '#/components/schemas/AgentsListResponse'
/api/v1/agents/{agentId}:
parameters:
- description: id of the agent
name: agentId
in: path
required: true
schema:
type: string
example: WmeA3Y51Q5ayCAaZ1AotIA
get:
tags:
- Agents
summary: Get Agent
operationId: Agents_getAgentProfile
description: |
Get an agent profile by their unique id.
responses:
'200':
description: Agent
content:
application/json:
schema:
$ref: '#/components/schemas/AgentsGetAgentProfileResponse'
/api/v1/agents/{agentId}/call-recorder:
parameters:
- description: Gladly ID or Gladly email address of the agent
name: agentId
in: path
required: true
schema:
type: string
example: WmeA3Y51Q5ayCAaZ1AotIA OR agent@customer.com
get:
tags:
- Agents
summary: Get Agent CallRecorder
operationId: Agents_getCallRecorderStatus
description: |
Get an agent call recording status.
responses:
'200':
description: CallRecorder
content:
application/json:
schema:
$ref: >-
#/paths/~1api~1v1~1agents~1%7BagentId%7D~1call-recorder/patch/requestBody/content/application~1json/schema
'404':
description: Agent not found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
code: not_exist
detail: agent WmeA3Y51Q5ayCAaZ1AotIA does not exist
patch:
tags:
- Agents
summary: Update Agent CallRecorder
operationId: Agents_updateCallRecorder
description: >
Update an agent's active call recording status. This API allows changing
the `recording` property.
requestBody:
description: JSON patch of CallRecorder
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AgentsUpdateCallRecorderRequest'
example:
recording: false
responses:
'204':
description: >-
Call recording updated. If an agent is not on a call the update will
do nothing.
'404':
description: Agent not found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
code: not_exist
detail: agent WmeA3Y51Q5ayCAaZ1AotIA does not exist
/api/v1/organization:
get:
tags:
- Organization
summary: Get organization
operationId: Organization_getMetadata
description: |
Returns metadata about your organization.
responses:
'200':
description: Organization
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationGetMetadataResponse'
/api/v1/inboxes:
get:
tags:
- Inboxes
summary: List inboxes
operationId: Inboxes_listMetadata
description: |
Returns a list of inbox metadata.
responses:
'200':
description: Inboxes
content:
application/json:
schema:
$ref: '#/components/schemas/InboxesListMetadataResponse'
/api/v1/inboxes/{inboxId}:
parameters:
- description: id of the inbox
name: inboxId
in: path
required: true
schema:
type: string
example: vZgCEQlDR6aQz_0HeWZ9_Q
get:
tags:
- Inboxes
summary: Get inbox
operationId: Inboxes_getMetadata
description: |
Get the metadata for an inbox by its unique id.
responses:
'200':
description: Inbox
content:
application/json:
schema:
$ref: '#/components/schemas/InboxesGetMetadataResponse'
/api/v1/teams:
get:
tags:
- Teams
summary: List teams
operationId: Teams_listTeams
description: |
Returns a list of teams.
responses:
'200':
description: Teams
content:
application/json:
schema:
$ref: '#/components/schemas/TeamsListTeamsResponse'
/api/v1/teams/{teamId}:
parameters:
- description: id of the team
name: teamId
in: path
required: true
schema:
type: string
example: ovg2jQCQS9ScsDkBxG-o2Q
get:
tags:
- Teams
summary: Get team
operationId: Teams_getById
description: |
Get a team by its unique id.
responses:
'200':
description: Team
content:
application/json:
schema:
$ref: '#/components/schemas/TeamsGetByIdResponse'
/api/v1/topics:
get:
tags:
- Topics
summary: List topics
operationId: Topics_list
description: |
Returns a list of topics.
responses:
'200':
description: Topics
content:
application/json:
schema:
$ref: '#/components/schemas/TopicsListResponse'
example:
- id: Z_Oto7j-Sy2DlQdnZBDdDw
disabled: false
name: Order Return
- id: 8eiDakrnTgKa3HIxtgV5OA
disabled: false
name: Damaged Merchandise
parentId: Z_Oto7j-Sy2DlQdnZBDdDw
- id: WgZnWNicSMmORcNzP8rwGQ
disabled: true
name: Holiday 2019
parentId: Z_Oto7j-Sy2DlQdnZBDdDw
/api/v1/topics/{topicId}:
parameters:
- description: id of the topic
name: topicId
in: path
required: true
schema:
type: string
example: uu4t00vITaKQ3bVjU2UrGQ
get:
tags:
- Topics
summary: Get topic
operationId: Topics_getById
description: |
Get a topic by its unique id.
responses:
'200':
description: Topic
content:
application/json:
schema:
$ref: '#/components/schemas/TopicsGetByIdResponse'
/api/v1/export/schedules:
get:
tags:
- Export
summary: List schedules
operationId: Export_listSchedules
description: >
List all schedules. Currently, only one schedule can be configured per
organization. The schedule will generate recurring data export jobs with
an hourly or daily frequency. By default, each organization has a daily
export job configured. To change the job frequency, please contact
Gladly Support.
Hourly schedules generate new jobs on a roughly two hour lag after the
`nextStartAt` time. For example, for an hourly schedule with a
`nextStartAt` equal to `2019-01-21T08:00:00.00Z`, the next job will be
created at approximately `2019-01-21T10:00:00.00Z`. Daily schedules will
run jobs during the night (UTC time).
responses:
'200':
description: found jobs
content:
application/json:
schema:
$ref: '#/components/schemas/ExportListSchedulesResponse'
/api/v1/export/jobs:
get:
tags:
- Export
summary: List jobs
operationId: Export_jobsList
description: >
List all jobs from the last 14 days using the following optional query
parameter:
```
/api/v1/export/jobs?status=COMPLETED
```
parameters:
- description: export job status to search on.
name: status
in: query
schema:
type: string
enum:
- PENDING
- IN_PROGRESS
- COMPLETED
- FAILED
responses:
'200':
description: found jobs
content:
application/json:
schema:
$ref: '#/components/schemas/ExportJobsListResponse'
/api/v1/export/jobs/{jobId}:
parameters:
- description: id of the job
name: jobId
in: path
required: true
schema:
type: string
example: OOrlNMXeS72gs_WEX2TtMg
get:
tags:
- Export
summary: Get job
operationId: Export_jobById
description: |
Get a job by unique id.
responses:
'200':
description: fetched job
content:
application/json:
schema:
$ref: '#/components/schemas/ExportJobByIdResponse'
links:
GetFilename:
operationId: getFile
description: >
The entries in `filenames` returned in the response can be used
as the the `filename` parameter in `GET
/api/v1/export/jobs/{jobId}/files/{filename}`
parameters:
filename: $response.body#/id
'404':
description: job not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrors'
delete:
tags:
- Export
summary: Delete job
operationId: Export_deleteJob
description: >
Delete a job and all associated files. *Note*: job status must be
`COMPLETED` or `FAILED` to be deleted.
responses:
'204':
description: the job was deleted
'400':
description: unable to delete job
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
- attr: status
code: temporary_failure
detail: >-
unable to delete job with status [IN_PROGRESS]. Please try
again after it has finished
'404':
description: job not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrors'
/api/v1/export/jobs/{jobId}/files/{filename}:
get:
tags:
- Export
summary: Get file
operationId: Export_downloadFile
description: >
Download a file generated by a data export job.
Filenames can be found from an export
[job's](index.html#operation/getJob) `files` field.
Files are returned in `.jsonl` format where each line is a `json` object
representing an element from the array of data. Please note that, in
rare cases, conversation items with invalid attributes may be excluded
from the data export. For example:
- An email message that was undelivered due to an invalid recipient
email address
- EMAIL / SMS auto-replies sent by Gladly to the customer via a Rule
Examples are as follows with schema below.
**agents.jsonl**
```
{"id": "WmeA3Y51Q5ayCAaZ1AotIA","name": "Amy Agent","emailAddress":
"amy.agent@company.com"}
```
**conversation_items.jsonl**
```
{"id": "ybP4szYCSy6LdV4DNwEd6g","conversationId":
"9BcE2O0DQ2ynGHRmk9FeoA","customerId":
"OOrlNMXeS72gs_WEX2TtMg","timestamp":
"2019-07-01T11:46:45.010Z","initiator": {"id":
"OOrlNMXeS72gs_WEX2TtMg","type": "CUSTOMER"},"content": {"type":
"CHAT_MESSAGE","sessionId": "5k04bYuTRGqyT6uoSQfWVA","content": "Hi! I
know it's after hours but can someone help upgrade my account?"}}
{"id": "9lQDrx-HTz-JMoP2T4CtZA","conversationId":
"9BcE2O0DQ2ynGHRmk9FeoA","customerId":
"OOrlNMXeS72gs_WEX2TtMg","timestamp":
"2019-07-02T06:30:12.070Z","initiator": {"id":
"WmeA3Y51Q5ayCAaZ1AotIA","type": "AGENT"},"content": {"type":
"EMAIL","from": "amy.agent@company.com","to":
["martha.williams@gmail.com"],"subject": "Account upgrade","content": "I
would be happy to help you! We need a few details, so please give us a
call this morning."}}
{"id": "QN1nURRuRne_eAEhW45UMA","conversationId":
"9BcE2O0DQ2ynGHRmk9FeoA","customerId":
"KgnVOMc2TbiA3zad6iVlWA","timestamp":
"2020-04-21T00:44:33.690Z","initiator":
{"type":"AGENT","id":"VjeJI9_GRUS_LUjKLcNlBw"},"responder":{"type":"CUSTOMER","id":"KgnVOMc2TbiA3zad6iVlWA"},"content":{"startedAt":"2020-04-21T00:44:34.604Z","answeredAt":"2020-04-21T00:44:45.515Z","completedAt":"2020-04-21T00:44:57.130Z","from":"+12096248260","to":"+14155335980","recordingUrl":"/api/v1/conversation-items/QN1nURRuRne_eAEhW45UMA/media/recording","recordingStatus":"AVAILABLE","recordingDuration":11,"type":"PHONE_CALL"}}
{"id": "K0UGL3n6S4uPpvtMvItqHA","conversationId":
"9BcE2O0DQ2ynGHRmk9FeoA","customerId":
"OOrlNMXeS72gs_WEX2TtMg","timestamp":
"2019-07-02T08:12:55.870Z","initiator": {"id":
"WmeA3Y51Q5ayCAaZ1AotIA","type": "AGENT"},"content": {"type":
"TOPIC_CHANGE","addedTopicIds": ["uu4t00vITaKQ3bVjU2UrGQ"]}}
{"id": "VMn_5L1iTPmcM5DBP1U8oQ","conversationId":
"9BcE2O0DQ2ynGHRmk9FeoA","customerId":
"KgnVOMc2TbiA3zad6iVlWA","timestamp":
"2020-04-21T00:56:03.712Z","initiator":
{"type":"CUSTOMER","id":"KgnVOMc2TbiA3zad6iVlWA"},
"content":{"startedAt":"2020-04-21T00:55:50.703Z","recordingUrl":"/api/v1/conversation-items/VMn_5L1iTPmcM5DBP1U8oQ/media/recording","recordingStatus":"AVAILABLE","recordingDuration":13,"type":"VOICEMAIL"}}
{"id": "SShWgSCHSHy6EO5TiL7rNw","conversationId":
"gHuxLQNXSAmmWuNePSyVTw","customerId":
"0EphnSIJR0ycjMWFTf-GXA","timestamp":
"2020-04-20T23:58:51.941Z","initiator":
{"type":"AGENT","id":"LsFXSnO6Ty6gdnyH6y8yug"},"content":{"type":"CONVERSATION_STATUS_CHANGE","status":"CLOSED"}}
{"id": "DnaU23pZSIqOixATlII1vA","conversationId":
"HXRqKC5GSV-jAlq0-sxYTA","customerId":
"o2sg-TMTSD2rTwMuxzewbA","timestamp":
"2020-04-24T23:42:57.780Z","initiator":
{"type":"AGENT","id":"zGaHXjD4SR-moMR9LbULDA"},"content":{"type":"CONVERSATION_NOTE","body":"Customer
has requested more information about our loyalty program."}}
```
**customers.jsonl**
```
{"id": "OOrlNMXeS72gs_WEX2TtMg","name": "Martha J Williams","address":
"563 Rigoberto Station Apt. 197","emailAddresses":
["Martha.Williams@gmail.com"],"phoneNumbers":
["+17244895501"],"externalCustomerId":
"a21c1636-c622-48b7-bf6a-d9032645aa55"}
```
**topics.jsonl**
```
{"id": "uu4t00vITaKQ3bVjU2UrGQ","name": "Order Returns","disabled":
false}
```
parameters:
- description: id of the job
name: jobId
in: path
required: true
schema:
type: string
example: OOrlNMXeS72gs_WEX2TtMg
- description: name of the file
name: filename
in: path
required: true
schema:
type: string
example: agents.jsonl
responses:
'200':
description: returns a file
content:
application/x-ndjson:
schema:
$ref: '#/components/schemas/ExportDownloadFileResponse'
examples: null
'404':
description: file not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrors'
/api/v1/reports:
post:
tags:
- Reports
summary: Generate a report
operationId: Reports_generateReportCsv
description: >-
Generate a report with a set of specific parameters and filters. The
report is returned as a CSV file. These are the same reports that you
can normally access via UI. For more information about each report,
check out the [Reporting and
Insights](https://help.gladly.com/docs/reports-key-concepts) section of
the help docs.
requestBody:
description: Parameters describing the report to generate.
content:
application/json:
schema:
$ref: '#/components/schemas/ReportsGenerateReportCsvRequest'
examples:
ContactSummaryReport:
value:
metricSet: ContactSummaryReport
timezone: America/Los_Angeles
startAt: '2021-10-01'
endAt: '2021-10-02'
aggregationLevel: daily
filters:
channel: allChannels
inboxes:
- c23d738960f946988e943f400313133a
- 2c475a4351ce4aa39ff5cb9f526d77db
IvrEndStatesReportV2:
value:
metricSet: IvrEndStatesReportV2
startAt: '2019-05-01'
endAt: '2019-05-16'
aggregationLevel: daily
filters:
phoneNumber: '+15555555555'
required: true
responses:
'200':
description: Report CSV
headers:
Content-Disposition:
schema:
type: string
example: >-
attachment;
filename=SummaryReportV2-20190501-20190516-Daily.csv
content:
text/csv:
schema:
$ref: '#/components/schemas/ReportsGenerateReportCsvResponse'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
invalid filter:
value:
errors:
- attr: filters.phoneNumber
code: invalid
detail: >-
the phoneNumber filter cannot be applied to the
SummaryReport metricSet
- attr: aggregationLevel
code: invalid
detail: the specified value is not a valid aggregation level
missing metricSet:
value:
errors:
- attr: metricSet
code: blank
detail: metricSet must be specified
nonexistent inbox:
value:
errors:
- attr: filters.inboxes
code: present
detail: the requested inbox does not exist
/api/v1/webhooks:
post:
tags:
- Webhooks
summary: Create webhook
operationId: Webhooks_createWebhook
description: >
Create a new webhook with the supplied data. The webhook will be in
disabled state by default.
If creating a new enabled webhook, your service is expected to respond
to a [Ping Event](https://developer.gladly.com/rest/).
You are limited to 20 webhooks for your organization.
requestBody:
description: Webhook to add
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksCreateWebhookRequest'
example:
name: CSAT integration
url: https://gateway.organization.com/gladly/webhook
events:
- CONVERSATION/CLOSED
credentials:
username: integrations@organization.com
password: fxdUfTcejVxVs9bQ8DizKccq
headers:
X-Gladly-Token: '123'
responses:
'201':
description: Created webhook
headers:
Location:
description: Location of the created webhook
schema:
type: string
example: /api/v1/webhooks/c5yeqK8VTlm9xAXgvq_5-w
'400':
description: Invalid field(s) in request body
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
callbacks:
event:
'{$request.body#/url}':
post:
requestBody:
content:
application/json:
schema:
$ref: >-
#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema
responses:
'200':
description: Event was accepted
get:
tags:
- Webhooks
summary: List webhooks
operationId: Webhooks_list
description: |
Returns a list of webhooks.
responses:
'200':
description: Webhook
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksListResponse'
/api/v1/webhooks/{webhookId}:
parameters:
- description: id of the webhook
name: webhookId
in: path
required: true
schema:
type: string
example: a9dIl-kKRrKUZLQtJ-tjtw
patch:
tags:
- Webhooks
summary: Update webhook
operationId: Webhooks_updateById
description: >
Update webhook by id.
If enabling a webhook or updating a webhook's URL, your service is
expected to respond to a [Ping
Event](https://developer.gladly.com/rest/).
requestBody:
description: JSON patch of webhook properties to insert or update
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksUpdateByIdRequest'
example:
enabled: true
responses:
'204':
description: Updated webhook
'400':
description: Invalid field(s) in request body
'404':
description: Webhook with id does not exist
delete:
tags:
- Webhooks
summary: Delete webhook
operationId: Webhooks_deleteById
description: |
Delete a webhook by ID
responses:
'204':
description: Webhook deleted
'400':
description: Webhook must be disabled to be deleted
'404':
description: Webhook with id does not exist
get:
tags:
- Webhooks
summary: Get webhook
operationId: Webhooks_getById
description: |
Get a webhook by ID
responses:
'200':
description: Webhook
content:
application/json:
schema:
$ref: >-
#/paths/~1api~1v1~1webhooks~1%7BwebhookId%7D/patch/requestBody/content/application~1json/schema
'404':
description: Webhook with id does not exist
/gladly/webhook:
servers:
- description: >-
Web service hosted on your servers should be reachable from the Gladly
cluster
url: https://gateway.organization.com
post:
tags:
- Payloads
operationId: Payloads_notifyEndpoint
description: >
Gladly will perform a POST request to your endpoint when the event
occurs.
Your service is expected to respond within 15 seconds.
If your service responds to a webhook notification with a response code
outside the 2XX range or times out after 15 seconds, Gladly considers
that delivery as failed and will resend the request up to 4 times over
an hour. After the fourth attempt, we will deactivate the webhook and
will notify all API Users in your organization's environment via email.
requestBody:
description: the event payload
content:
application/json:
schema:
$ref: '#/components/schemas/PayloadsNotifyEndpointRequest'
responses:
'200':
description: Success
/api/v1/reports/work-session-events:
post:
tags:
- Reports
summary: Generate a work session report
operationId: Reports_generateWorkSessionReport
description: >
A **Work Session** represents a period of time that an Agent spends
working with a Customer on a given channel, during a given Contact
(messaging exchange, phone call, etc.). In particular:
- A Customer may have 0 or more Conversations, but only 1 Conversation is open at any given time.
- A Conversation may contain 0 or more Contacts (e.g.: A single phone call, a chat session, an email session).
- A Contact may have 0 or more Work Sessions (i.e.: Agents who work on the Contact).
- A Work Session is the unique combination of contact_session_id and agent_id. The agent_id column will be NULL if the contact has not been handled by any Agent.
The Work Session Report API contains **both** contacts and work
sessions. It allows you to understand what your inbound contact volume
looks like, and to get a view into how Agents are using their time. The
primary use of this information is for forecasting and scheduling
purposes, but it can also be used to understand, at a fine-grained
level, aspects of agent behavior, agent performance, multichannel
conversation patterns and more.
The time anchor for data returned by this API is
COALESCE(contact_session_created_at, contact_session_ended_at) (i.e.: if
contact_session_ended_at does not exist, use contact_session_created_at.
Otherwise, use contact_session_ended_at).
This means that if it is currently 2023-03-23T00:00Z and:
- contact_session_id A was created on 2023-03-21T04:00Z and ended on 2023-03-22T04:00Z
- You set the startAt time filter to 2023-03-21T00:00Z
- You set the endAt time filter to 2023-03-22T00:00Z
- You would not be able to retrieve contact_session_id A in your API request. Instead, you will need to set the endAt time filter to now() (aka 2023-03-23T00:00Z) to retrieve the contact information.
Therefore, the general recommendation to get correct data is always to
set the endAt time to now() rather than the end interval you'd like to
analyze - this will accomodate contacts that "move" intervals due to
ending.
Note that:
- work_session_unknown_time_sec and work_session_after_contact_time_sec may accumulate after the contact ends and before the conversation ends / another contact begins
- work_session_handle_time_sec will only be available for a contact after it ends
- This report is subject to the same [data latency](https://help.gladly.com/docs/why-is-my-reporting-data-not-current) as other Gladly reports
This CSV file contains the following columns, whose definitions may be
viewed via the [Work
Sessions](https://help.gladly.com/docs/work-sessions) section of the
help docs.
- id
- contact_session_id
- contact_session_created_at
- customer_id
- conversation_id
- inbox_id
- channel
- direction
- agent_accepted_at
- contact_session_routed_at
- agent_id
- sla_fulfilled_at
- contact_session_ended_at
- status
- within_sla
- work_session_handle_time_sec
- work_session_after_contact_time_sec
- work_session_unknown_time_sec
- accepted_inbox_id
requestBody:
description: A time range for the report that will be generated.
content:
application/json:
schema:
$ref: '#/components/schemas/ReportsGenerateWorkSessionReportRequest'
example:
startAtTime: 2020-04-13T19:27-09:00
endAtTime: 2020-04-14T19:27-09:00
required: true
responses:
'200':
description: Work Session Report CSV
headers:
Content-Disposition:
schema:
type: string
example: >-
attachment;
filename=WorkSessionEventsReport-20200302T1000Z-20200302T2000Z.csv
content:
text/csv:
schema:
$ref: '#/components/schemas/ReportsGenerateWorkSessionReportResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
invalid parameter:
value:
errors:
- attr: startAtTime
code: invalid
detail: endAtTime must occur after startAtTime
/api/v1/events:
parameters:
- description: >
Starting time of the events interval. This is based on the `timestamp`
field which indicates when the event was recorded. Must be from last
24 hours.
The date should be in ISO 8601 format.
name: startAt
required: true
in: query
schema:
type: string
example: '2020-04-13T19:27:34-09:00'
- description: >
Ending time of the events interval. This is based on the `timestamp`
field which indicates when the event was recorded. If unspecified,
current time will be implied.
The date should be in ISO 8601 format.
name: endAt
in: query
required: false
schema:
type: string
example: '2020-04-13T20:27:12-09:00'
- description: >
Entity types that have associated events. Any number of types is
acceptable and at least one must be present
Available Types: `AGENT_AVAILABILITY`, `AGENT_STATUS`, `CONTACT`,
`CONVERSATION`, `CUSTOMER`, `PAYMENT_REQUEST`,`TASK`
name: entities
required: true
in: query
schema:
type: array
example:
- AGENT_AVAILABILITY
- AGENT_STATUS
items:
description: >-
WARNING: Missing items property in array schema. Missing items
property has been filled with this AnyType schema.
get:
tags:
- Events
summary: List events
operationId: Events_listStreamOfEvents
description: >
Returns a stream of events for the specified entities within the given
time range. Responses are streamed using JSONL.
Events are up to 15 seconds behind real-time.
```
/api/v1/events?startAt=2020-05-20T14:00:00Z&entities=AGENT_STATUS&entities=AGENT_AVAILABILITY
```
responses:
'200':
description: Events Streaming Response
content:
application/x-jsonlines:
schema:
$ref: '#/components/schemas/EventsListStreamOfEventsResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
invalid parameter:
value:
errors:
- attr: startAt
code: invalid
detail: endAt must occur after startAt
components:
securitySchemes:
BasicAuth:
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
```
type: http
scheme: basic
schemas:
Error:
type: object
properties:
attr:
description: Identifies the field causing the error
type: string
code:
description: Code indicating the error type
type: string
detail:
description: More details describing what went wrong
type: string
Errors:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/Error'
example:
- attr: content
code: blank
detail: content cannot be blank
NotFoundErrors:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/Error'
example:
- code: not_exist
detail: entity does not exist
CommunicationsSendSmsRequest:
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!
CommunicationsReceiveCustomChannelMessagesRequest:
title: Custom Channel Message request body
type: object
required:
- sender
- to
- type
- content
properties:
sender:
type: object
required:
- address
properties:
address:
description: >
The address is used to map inbound messages to the Customer
Profile. This address is a unique identifier
of the Gladly Customer.
type: string
displayName:
title: Optional
description: >
The message sender's display name shown on the contact details
card.
type: string
profileIdentifier:
title: Optional
description: >
The profileIdentifier allows associating the message with other
identifiable addresses of a Customer.
We will use the profileIdentifier when the first message is
received and link the sender address to a Gladly
Profile that has a matching identifier. If no existing Profile
exist with a matching identifier, a new Profile
with the identifier will be created.
required:
- type
- address
properties:
type:
title: the identifier type
type: string
enum:
- EMAIL
- PHONE_NUMBER
address:
title: the identifier address
description: >
Depending on the type, this should either be an email
address or a phone number in E.164 format.
type: string
to:
description: >
The address of the recipient of the message. This should correspond
to the Entry Point Address
created for the Custom Channel in Gladly.
type: string
type:
description: |
Describes the message type
type: string
enum:
- TEXT
- FILES
groupId:
title: Message Group ID
description: >
Optional message group ID that can be associated with a message, the
Custom Channel must be configured for
Message Groups in order to use this field.
type: string
groupName:
title: Message Group Name
description: >
Used together with `groupId` to give the group a name that can be
displayed to an Agent.
type: string
content:
oneOf:
- title: Plain text message
description: |
Plain text message
required:
- text
properties:
text:
description: |
Plain text content on the message
type: string
- title: Files message
description: >
A message that has attached files, this could be images or other
types of files.
required:
- files
properties:
caption:
description: |
Optional text describing the files
type: string
files:
type: array
items:
title: A file description
type: object
required:
- url
properties:
fileName:
description: Optional name of file
type: string
url:
description: >-
Publicly available URL where file can be downloaded
from
type: string
CommunicationsUpdateMessageStatusRequest:
title: Custom Channel Message status
type: object
required:
- value
properties:
value:
type: string
enum:
- ACCEPTED
- DELIVERED
- READ
- FAILED
details:
description: >-
Optional status details. It is particularly useful when the value is
'Failed'.
type: string
ConversationsUpdateAssigneeStatusRequest:
title: Conversation Update
type: object
properties:
assignee:
title: Assignee Update
type: object
required:
- inboxId
properties:
agentId:
description: The id of the agent who is assigned to the conversation
type: string
example: sHuXx-U3QqOmhvFusJGeBw
inboxId:
description: The id of the inbox to which the conversation belongs to
type: string
example: E1nArq1uQAees_DogHB0MA
status:
title: Conversation Status
type: object
required:
- value
properties:
value:
description: Value of the status to change to
type: string
enum:
- CLOSED
- OPEN
force:
description: >-
Determines whether to override the value if conversation still
needs a response
type: boolean
default: false
ConversationsCreateCustomerItemRequest:
title: Conversation Item To Create with Customer
required:
- content
- customer
type: object
properties:
id:
description: >-
Unique conversation item id. Must be URL safe and under 50
characters. An id will be automatically generated if one is not
included.
maxLength: 50
type: string
example: pOVVdzweSumI4bFxjlT8LA
customer:
title: Customer Specification
description: >-
Specifies the customer an item belongs to. You must provide exactly
one of the values.
type: object
properties:
emailAddress:
type: string
example: michelle.smith@example.org
mobilePhone:
type: string
example: '+16505551987'
content:
title: Conversation Item Content To Create
oneOf:
- title: Customer Activity
description: >-
An event such as consumer interaction outside Gladly that agents
will see in the customer timeline.
required:
- activityType
- type
type: object
properties:
title:
description: >-
First line of highlighted text for the item in the customer
timeline
maxLength: 100
type: string
example: Welcome to Gladly!
type:
type: string
example: CUSTOMER_ACTIVITY
enum:
- CUSTOMER_ACTIVITY
body:
description: >-
Plain text or rich content ([see here for supported
markup](https://developer.gladly.com/rest/)) of the activity
that will appear as the main content.
maxLength: 25000
type: string
example: >-
At Gladly we set out to reinvent customer service. Why?
Because 21st century consumers are different. They are from
18 to 80 years old, expect the brands they love to recognize
them, and to be able to communicate with your agents over
all channels – all the time.
activityType:
description: >-
Type of this activity. This will determine the icon
displayed in the customer timeline.
type: string
example: EMAIL
enum:
- EMAIL
- ISSUE
- SMS
- SURVEY
sourceName:
description: Name of the source system generating this activity
maxLength: 50
type: string
example: HubSpot
link:
description: >-
Clickable reference to appear at the bottom portion of the
customer activity card in the customer timeline
type: object
properties:
url:
description: URL for a clickable link that this item should go to
type: string
example: https://www.gladly.com/product/
text:
description: Text label for the link
maxLength: 50
type: string
example: View Details
occurredAt:
description: >-
Time when this activity occurred. Will determine where in
the customer timeline this item appears. Limited to events
no older than 1 year. Note if this value is not set, it will
be ommitted from the GET Item API call, and ordering on the
timeline will default to the `receivedAt` time (i.e.:
`current_time`).
type: string
format: RFC3339 with millis
example: '2016-04-11T14:09:23.000Z'
receivedAt:
description: The time when this item was first sent to Gladly
type: string
format: RFC3339 with millis
readOnly: true
example: '2019-01-11T20:49:55.000Z'
- title: Task (deprecated)
required:
- body
- dueAt
- type
- assignee
type: object
properties:
type:
type: string
example: TASK
enum:
- TASK
assignee:
title: Assignee
description: Inbox and Agent assignee for a Task
required:
- inboxId
properties:
inboxId:
description: >-
Id of the inbox the task should be assigned to. You can
look up the id in the Gladly UI.
type: string
example: NFpDZtfqhk2pI6fjaVDlFf
agentId:
description: >-
Id of the agent the task should be assigned to. You can
look up the id in the Gladly UI.
type: string
example: zGaHXjD4SR-moMR9LbULDa
body:
description: >-
Text to describe what task to complete. Constrained HTML
[Rich Content](https://developer.gladly.com/rest/) is
supported.
maxLength: 10000
type: string
example: Call customer back with information about booking
dueAt:
description: >-
Time when the task will be due. This must be set to a time
in the future.
type: string
format: RFC3339
example: '2020-03-15T06:13:00.125Z'
ConversationsCreateCustomerItemRequest1:
title: Conversation Item To Create
required:
- content
type: object
properties:
id:
description: >-
Unique conversation item id. Must be URL safe and under 50
characters. An id will be automatically generated if one is not
included.
maxLength: 50
type: string
example: pOVVdzweSumI4bFxjlT8LA
content:
$ref: >-
#/paths/~1api~1v1~1conversation-items/post/requestBody/content/application~1json/schema/properties/content
ConversationsAddTopicToListRequest:
title: List of Conversation Topics to Add
required:
- topicIDs
type: object
properties:
topicIds:
description: Topic Ids to be added to the conversation.
type: array
example:
- pOVVdzweSumI4bFxjlT8LA
items:
type: string
ConversationsAddFreeformTopicsRequest:
title: List of Conversation Freeform Topics to Add or Remove
required:
- content
type: object
properties:
body:
description: Freeform topics that need to be added or removed from a conversation
type: string
items:
type: object
ConversationsAddNoteToConversationRequest:
title: Content of note to add
required:
- content
type: object
properties:
body:
description: >-
Plain text or [rich content](https://developer.gladly.com/rest/) of
the note.
type: string
example: >-