openapi: 3.0.1
info:
title: Gladly Agents Conversations API
version: '1.0'
description: '# Introducing the Gladly API
At Gladly, we believe that customer service is best when it''s a conversation.
That means more than just helping customers with one-off questions or issues: it''s about making them feel known, valued, and respected for the individuals they are.
The Gladly API was built to help facilitate those relationships, providing agents with the rich customer context
they need to deliver seamless experiences that make customers feel like they''re more than just a number in a sea of others.
# Overview
You can integrate easily with Gladly by calling Gladly''s [REST API](#section/Overview/REST-API)
and implementing the [Lookup API](#section/Overview/Lookup-API) to provide data from your own services.
Some examples of what you do through Gladly APIs include managing customer profile data, interacting with a customer''s timeline,
providing the latest information about a customer''s orders, and more.
## REST API
Clients can access the **REST API** via HTTPS at your organization''s Gladly domain (e.g. `https://{organization}.gladly.com`).
Resources follow REST semantics and utilize industry-standard HTTP verbs, response codes, and authentication schemes.
In addition, all responses and payloads are in JSON with consistent error codes and formats.
## Lookup API
The Gladly **Lookup API** allows your organization to provide data services to power the agent''s experience with a complete view of your customers''
information, transactions, and activity. You can provide a web service that implements the Lookup API and Gladly will call it when that data is needed.
Like the REST API, the Lookup API is specified using REST semantics, and exchanges JSON requests and responses authenticated and signed with secure keys.
Gladly will perform lookups when certain activities occur within Gladly, such as when a customer''s profile is loaded.
A detailed overview of Lookup Adaptor architecture, requests, resposnes and more can be found [here](https://help.gladly.com/developer/docs/lookup-adapter-introduction).
## Testing
Test the myriad possibilities of the Gladly API in a safe, secure space. We''ll enable the Gladly API in a separate sandbox environment, so you can experiment freely without impacting your production environment (or vice versa).
Your sandbox environment is accessible at `https://{organization}.gladly.qa`, where `organization` is your company name. For specific API endpoints, see documentation below.
# Getting Started
Think of this section as getting the keys to unlocking your access to the Gladly APIs.
First, you''ll need to set up an account with the necessary API [permissions](#/section/Getting-Started/Permissions).
With these permissions, you can then go on to create the [API Token(s)](#section/Getting-Started/Creating-API-Tokens) you need to access Gladly''s API [resources](#section/Overview/Resources).
## Permissions
Gladly Administrators can set API permissions on an agent-by-agent basis.
We''ll discuss how this maps to API access in the section on [authentication](#section/Authentication) below.
To allow a user to create API tokens and access the API:
1. Log in to your Gladly instance.
2. Open the menu on the top left-hand corner of the page.
3. Navigate to **Settings** > **Users*
4. Search and click the user profile you wish to give access to.
5. You''ll see a permission called **API User**. Select it, while making sure to keep the user''s **Agent** role intact.
6. Hit **Save** to give access.
We recommend creating a dedicated user to make API calls, whose account won''t be used for agent and organization management.
This will help you with any future audits of API activity vs. agent activity.
## Creating API Tokens
You must create an API token to access Gladly API resources (see above [Permissions](#/section/Getting-Started/Permissions)).
If your profile already has access to the **API User** permission, you''ll see a menu item titled **More settings**. Click **More settings**:
Click **API Tokens**, then the **Create Token** button on the upper right-hand corner of the page:
A token will be generated and named, by default, **New Token** (though depending on whether you have existing tokens, it may be named New Token 2, or New Token 3, etc.).
You can rename the token to something more easily referenceable by clicking the name to edit.
This token will be associated with your agent profile, which we refer to as the API User in this document.
For security purposes, you''ll only see a new token once before you navigate away from the page.
## Replacing/Rotating API Tokens
Should you lose this token, or wish to rotate your application keys, you can do the following:
1. Generate a new token.
2. Store the new token in a secure location.
3. Delete the old token.
4. Update your applications/scripts with the new token.
# Authentication
<!-- ReDoc-Inject: <security-definitions> -->'
servers:
- url: https://{organization}.gladly.com/api/v1
description: Production
variables:
organization:
default: organization
description: Your Gladly organization subdomain
- url: https://{organization}.gladly.qa/api/v1
description: Sandbox
variables:
organization:
default: organization
description: Your Gladly QA organization subdomain
security:
- basicAuth: []
tags:
- name: Conversations
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 |
| 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 |
| Voice AI Message | A spoken message exchanged with Gladly''s voice AI during a voice AI session | No | Yes | No | No | 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](#operation/sendSMS).
### Task
Interacting with tasks through the conversations API is deprecated. Use [Tasks API](#tag/Tasks) 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.
### Voice AI Message
A spoken message exchanged between a customer and Gladly''s voice AI during a voice AI session.
### Voicemail
Information about voicemail left by customers in Gladly.
### WhatsApp
Content of messages sent between Gladly and customers on WhatsApp.
'
paths:
/api/v1/customers/{customerId}/conversations:
get:
tags:
- Conversations
summary: Get Conversations for Customer
description: 'Get the list of conversations for a customer.
The list is not paginated and will return at most 100 conversations.
The conversations are returned in ascending order by timestamp.
The `Gladly-Limited-Data` header flag in the response will indicate if the customer has more conversations than returned.
'
operationId: getConversations
parameters:
- in: path
name: customerId
schema:
type: string
required: true
description: Id of the customer to get all conversations for
example: gHufx-U3QqOmhvFuViceTw
responses:
'200':
description: The conversations for the customer
content:
application/json:
schema:
title: Conversations
type: array
items:
$ref: '#/paths/~1api~1v1~1conversations~1%7BconversationId%7D/get/responses/200/content/application~1json/schema'
examples:
Conversations:
summary: Example of conversations response
value:
- id: HXRqKC5GSV-jAlq0-sxYTA
topicIds:
- _DZTz4I0Qsq9YXxeXwufMg
- tYVmwhIVQe-2tflRIszQ3g
customAttributes:
- id: UCeBpdBVSNyaP54jhd8CZw
value: '1234556777'
- id: UCeBpdBVSNyaP54jhd8CZw
value: '883399334403'
- id: cEBkE90eQHObfcsnrm60Tg
value: UPS
customerId: o2sg-TMTSD2rTwMuxzewbA
createdAt: '2016-01-02T00:10:00Z'
agentId: sHuXx-U3QqOmhvFusJGeBw
inboxId: E1nArq1uQAees_DogHB0MA
status: OPEN
- id: UMTZxwzJRyejwOj4NDfjeg
topicIds:
- tYVmwhIVQe-2tflRIszQ3g
customAttributes:
- id: UCeBpdBVSNyaP54jhd8CZw
value: '1234556777'
- id: UCeBpdBVSNyaP54jhd8CZw
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: CLOSED
/api/v1/conversations/{conversationId}:
get:
tags:
- Conversations
summary: Get Conversation
description: 'Get conversation metadata such as it''s assignee, topics, inbox, etc.
'
operationId: getConversation
parameters:
- in: path
name: conversationId
schema:
type: string
required: true
description: Id of the conversation to get
example: 9BcE2O0DQ2ynGHRmk9FeoA
responses:
'200':
description: Conversation metadata
content:
application/json:
schema:
title: Conversation
type: object
required:
- id
- customerId
- createdAt
- inboxId
- status
properties:
id:
type: string
description: The id of the conversation
example: pOVVdzweSumI4bFxjlT8LA
customerId:
type: string
description: The id of the profile that this conversation belongs to
example: gHufx-U3QqOmhvFuViceTw
agentId:
type: string
description: The id of the agent who is assigned to the conversation
example: sHuXx-U3QqOmhvFusJGeBw
inboxId:
type: string
description: The id of the inbox to which the conversation belongs to
example: E1nArq1uQAees_DogHB0MA
customAttributes:
type: array
description: Custom attributes assigned to the conversation
items:
title: Custom Attribute
description: Specifies a custom attribute
type: object
properties:
id:
type: string
description: id of the custom attribute
example: pOVVdzweSumI4bFxjlT8LA
value:
type: string
description: value of the custom attribute
example: '1234567890'
topicIds:
type: array
description: Ids of topics assigned to the conversation
items:
type: string
createdAt:
type: string
format: RFC3339 with millis
description: Time the conversation was created
example: '2016-04-11T14:09:23.000Z'
closedAt:
type: string
format: RFC3339 with millis
description: Time the conversation was closed. Only present if conversation is closed
example: '2016-05-10T13:49:23.000Z'
status:
title: Conversation Status
type: string
enum:
- OPEN
- WAITING
- CLOSED
description: "Status of the conversation:\n * `OPEN` - conversation requires further action\n * `WAITING` - no further action from an agent required. Waiting for response from the customer\n * `CLOSED` - resolved and requiring no further action. It can be changed back to OPEN if customer needs further assistance\n"
example: OPEN
examples:
Conversation:
summary: Example of a conversation response
value:
id: HXRqKC5GSV-jAlq0-sxYTA
topicIds:
- _DZTz4I0Qsq9YXxeXwufMg
- tYVmwhIVQe-2tflRIszQ3g
customAttributes:
- id: UCeBpdBVSNyaP54jhd8CZw
value: '1234556777'
- id: UCeBpdBVSNyaP54jhd8CZw
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: CLOSED
'404':
description: A conversation with the given id does not exist
patch:
tags:
- Conversations
summary: Update Conversation
description: 'Update conversation assignee, statusor both
'
operationId: patchConversation
parameters:
- in: path
name: conversationId
schema:
type: string
required: true
description: Id of the conversation
example: 9BcE2O0DQ2ynGHRmk9FeoA
requestBody:
required: true
description: JSON representation of conversation updates
content:
application/json:
schema:
title: Conversation Update
type: object
properties:
assignee:
type: object
title: Assignee Update
required:
- inboxId
properties:
agentId:
type: string
description: The id of the agent who is assigned to the conversation
example: sHuXx-U3QqOmhvFusJGeBw
inboxId:
type: string
description: The id of the inbox to which the conversation belongs to
example: E1nArq1uQAees_DogHB0MA
status:
type: object
title: Conversation Status
required:
- value
properties:
value:
type: string
description: Value of the status to change to
enum:
- CLOSED
- OPEN
force:
type: boolean
description: Determines whether to override the value if conversation still needs a response
default: false
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
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.
'
operationId: createItem
requestBody:
description: Conversation Item to create
content:
application/json:
schema:
title: Conversation Item To Create with Customer
required:
- content
- customer
type: object
properties:
id:
maxLength: 50
type: string
description: Unique conversation item id. Must be URL safe and under 50 characters. An id will be automatically generated if one is not included.
example: pOVVdzweSumI4bFxjlT8LA
customer:
$ref: '#/paths/~1api~1v1~1tasks/post/requestBody/content/application~1json/schema/properties/customer'
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:
type:
type: string
example: CUSTOMER_ACTIVITY
enum:
- CUSTOMER_ACTIVITY
title:
maxLength: 100
type: string
description: First line of highlighted text for the item in the customer timeline
example: Welcome to Gladly!
body:
maxLength: 25000
type: string
description: Plain text or rich content ([see here for supported markup](#tag/Rich-Content)) of the activity that will appear as the main content.
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:
type: string
description: Type of this activity. This will determine the icon displayed in the customer timeline.
example: EMAIL
enum:
- EMAIL
- ISSUE
- SMS
- SURVEY
sourceName:
maxLength: 50
type: string
description: Name of the source system generating this activity
example: HubSpot
link:
type: object
properties:
url:
type: string
description: URL for a clickable link that this item should go to
example: https://www.gladly.com/product/
text:
maxLength: 50
type: string
description: Text label for the link
example: View Details
description: 'Clickable reference to appear at the bottom portion of the customer activity card in the customer timeline '
expandByDefault:
type: boolean
description: Whether the activity should be expanded by default in the customer timeline
example: true
default: false
occurredAt:
type: string
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`).'
format: RFC3339 with millis
example: '2016-04-11T14:09:23.000Z'
receivedAt:
type: string
description: The time when this item was first sent to Gladly
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:
$ref: '#/paths/~1api~1v1~1tasks/post/requestBody/content/application~1json/schema/properties/assignee'
body:
maxLength: 10000
type: string
description: Text to describe what task to complete. Constrained HTML [Rich Content](#tag/Rich-Content) is supported.
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'
attachments:
type: array
description: attachments to the task
items:
$ref: '#/paths/~1api~1v1~1conversations~1%7BconversationId%7D~1notes~1%7BnoteId%7D/get/responses/200/content/application~1json/schema/properties/content/properties/attachments/items'
examples:
Customer Activity:
summary: Example of a Customer Activity
value:
id: pOVVdzweSumI4bFxjlT8LA
customer:
emailAddress: michelle.smith@example.org
content:
type: CUSTOMER_ACTIVITY
title: Welcome to Gladly!
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:
title: Conversation Item To Create
type: object
required:
- content
- timestamp
properties:
id:
type: string
description: the id of the item
example: pOVVdzweSumI4bFxjlT8LA
customerId:
type: string
description: the id of the profile that this item belongs to
example: gHufx-U3QqOmhvFuViceTw
timestamp:
type: string
format: RFC3339
description: Time the item occurred
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1api~1v1~1tasks~1%7BtaskId%7D/get/responses/200/content/application~1json/schema/properties/createdBy'
responder:
title: Describes the communicator initiating or responding to the item
type: object
properties:
id:
type: string
description: id of the communicator
example: zGaHXjD4SR-moMR9LbULDa
type:
type: string
description: 'type of communicator which can be an agent, customer, a person related to customer, rule, or application
If an email response comes from a third-party recipient who was previously included in an email exchange with the customer (TO, CC, or BCC), the reply''s initiator type will be either ''INTERNAL'' or ''EXTERNAL'' depending on the sender''s email address domain. ''INTERNAL'' types are sent from email addresses that share domain with the agent''s organization. ''EXTERNAL'' types are sent from other domains.
initiator.id=SIDEKICK_V2 and initiator.type=SYSTEM are set when the responder is Gladly AI. Note that Structured Threads (legacy) responses will still have init
# --- truncated at 32 KB (103 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gladly/refs/heads/main/openapi/gladly-conversations-api-openapi.yml