openapi: 3.0.1
info:
title: Gladly 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
'
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
tags:
- name: Agents
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: Public Answer
description: 'A **Public Answer** in Gladly represents a consumer-facing Answer.
The Public Answers API allows you to search and retrieve Public Answers (created
directly in the Gladly UI), which you can display in the Chat
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 Chat Web widget
'
- name: Answer Management
description: "The **Answer Management API** allows you to create, update, and delete Answers in Gladly. To create an Answer\
\ with content, two calls would be needed. \nOne call to create an Answer and subsequent call(s) to add content(s)\n"
- name: Audiences
description: 'An **Audience** represents a brand (or segment) specially for a multi-brand company. They are used to categorize
Answers, Help Centers and Chats for the specific brands.
The API allows you to lookup the audiences that have been created for the organization.
'
- name: Communications
description: 'Communications API enables you to programmatically send messages to your customers. These messages are non-routable
and non-searchable.
### Agent View
### Consumer View
'
- name: Customers
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: 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.
'
- name: Export
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: Events
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: Freeform Topics
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. \n\nNote: 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.\n"
- name: Reports
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: Organization
description: 'An **Organization** contains metadata about your company that Gladly is configured with.
'
- name: Inboxes
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: Proactive Conversations
description: 'A proactive conversation consists of a **campaign** and **recipients**. This APIs intended use-case would
be to provide status updates to a customer and not for marketing purposes.
'
- name: Tasks
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: Teams
description: 'A **Team** represents a group of Agents. They may handle particular **Inboxes** or types of work within Gladly.
'
- name: Business Hours
description: '**Business Hours** define the operating schedule for your organization. They determine when your organization
is available to handle customer communications and can be used to control routing, auto-responses, and other time-sensitive
workflows.
Business hours configurations include:
- **Schedule blocks** for each day of the week specifying start and end times
- **Timezone** in IANA format (e.g., America/Los_Angeles)
- **Exceptions** for holidays or special dates
One business hours configuration is marked as **primary** and serves as the default schedule for your organization. The
primary business hours cannot be deleted.
'
- name: Topics
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: Webhooks
description: 'A **Webhook** is a way to send notifications about Gladly events as a POST request to the endpoint of your
choice.
'
- name: Summary
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.\n\nSimply 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.\n\nConfigure webhooks using the\
\ [Webhooks API](#operation/createWebhook) or the Webhooks Admin Page.\n\nUsers with API User permissions can configure\
\ webhooks by navigating to Integrations > Webhooks.\n\n\n\n## Securing\
\ Webhooks\nWe provide two methods for your web service to authenticate requests from Gladly.\nWe recommend implementing\
\ at least one **authentication** option.\n\n### Basic Authentication\n\nFor 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.\n\n### Header Based Token Authentication\n\nFor 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.\n\n## Ping Event\nWhenever you\
\ enable a webhook or update a webhook's URL, we'll send you a special `PING` event.\n\nYour 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.\n\n## Retry Policy\n\n**Effective 6/28/23**\n\nIf 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. \n\nTo 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.\n\nThe following table shows the intervals between\
\ each retry attempt.\n\n| Attempt | Retry interval |\n| ------- | ------------------------ |\n| 1 | 30\
\ seconds |\n| 2 | 5 minutes |\n| 3 | 30 minutes |\n| 4 |\
\ 1 hour |\n\n## Logs\nWe 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.\n\n\n\
\nEach 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.\nFor more information about webhook logs, please see our [Help Documentation](https://connect.gladly.com/docs/help-documentation/article/reactivate-deactivated-webhooks/?highlight=webhook).\n\
\n## Payloads\nGladly payloads are intentionally small: they contain only Gladly IDs and event names rather than the object/data\
\ that has been modified or created\n\nThis 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.\n\nTo 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](#operation/getConversation) or the [List Items in Conversation API](#operation/getConversationItems).\n\
\n## Available Events\nPlease see the [Help Documentation](https://help.gladly.com/docs/reporting-concepts) for more information\
\ about many of the events listed below.\n\n| Event | Triggered by Gladly when: \
\ |\n| ------------------------------| --------------------------------------------------------------|\n\
| AGENT_AVAILABILITY/UPDATED | an Agent's availability is updated |\n| AGENT_STATUS/CHANGED_ACTIVE_REASON | an\
\ Agent's active reason is updated |\n| AGENT_STATUS/LOGGED_IN | an Agent logs in |\n| AGENT_STATUS/LOGGED_OUT\
\ | an Agent logs out |\n| AGENT_STATUS/RETURNED_FROM_AWAY | an Agent returns from away |\n| AGENT_STATUS/WENT_AWAY\
\ | an Agent goes away |\n| CONTACT/ENDED | a Contact is ended |\n| CONTACT/FULFILLED\
\ | a Contact's SLA is fulfilled |\n| CONTACT/HOLD_ENDED | a Contact's hold is ended\
\ |\n| CONTACT/HOLD_STARTED | a Contact's hold is started |\n| CONTACT/JOINED | an Agent\
\ joins a Contact |\n| CONTACT/MESSAGE_RECEIVED | a Message is received |\n| CONTACT/MESSAGE_SENT \
\ | a Message is sent |\n| CONTACT/OFFER_ACCEPTED | a Contact's offer is accepted |\n| CONTACT/OFFERED\
\ | a Contact is offered |\n| CONTACT/OFFER_REJECTED | a Contact's offer is rejected |\n\
| CONTACT/STARTED | a Contact is started |\n| CONTACT/TRANSFERRED | a Contact is transferred\
\ |\n| CONVERSATION/CLOSED | a Conversation is closed |\n| CONVERSATION/CREATED\
\ | a new Conversation is created |\n| CONVERSATION/CUSTOM_ATTRIBUTE_ADDED\
\ | a custom attribute has been added to the conversation |\n| CONVERSATION/CUSTOM_ATTRIBUTE_REMOVED\
\ | a custom attribute has been removed from the conversation |\n| CONVERSATION/NOTE_CREATED\
\ | a Note is added to a Conversation |\n| CONVERSATION/REOPENED | a Conversation is reopened\n\
| CONVERSATION/TOPIC_ADDED | a topic is added to a Conversation |\n| CONVERSATION/TOPIC_REMOVED | a\
\ Conversation's topic is removed |\n| CONVERSATION_ASSIGNEE/UPDATED | a Conversation's assignee (inbox and/or Agent)\
\ changes |\n| CONVERSATION_STATUS/UPDATED | a Conversation changes statuses (e.g.: from OPEN to CLOSED)\
\ |\n| CUSTOMER/MERGED | a Customer Profile is merged with another profile |\n| CUSTOMER_PROFILE/CREATED\
\ | a Customer Profile is created |\n| CUSTOMER_PROFILE/DELETED |\
\ a Customer Profile is deleted |\n| CUSTOMER_PROFILE/MERGED | a Customer Profile\
\ is merged with another profile |\n| CUSTOMER_PROFILE/UPDATED | a Customer Profile is updated (e.g.:\
\ name is updated) |\n| EXPORT_JOB/COMPLETED | a [data export job](#operation/findJobs) is completed\
\ |\n| EXPORT_JOB/FAILED | a [data export job](#operation/findJobs) fails\
\ to complete |\n| PAYMENT_REQUEST/CREATED | a payment request is created |\n| PAYMENT_REQUEST/STATUS_CHANGED\
\ | a payment request's status changes |\n| PAYMENT_REQUEST/VIEWED | a payment request is viewed by the\
\ Customer |\n| PING | a webhook is initially created to verify serivce availability |\n\
| TASK/ASSIGNEE_UPDATED | a task's assignee is updated |\n| TASK/CLOSED | a task is\
\ closed |\n| TASK/COMMENT_ADDED | a comment is added to a task |\n| TASK/CONTENT_UPDATED \
\ | the content of a task is updated |\n| TASK/CREATED | a task is created |\n| TASK/DUE_DATE_UPDATED\
\ | the due date of a task is updated |\n| TASK/FOLLOWER_ADDED | a follower is added to a\
\ task |\n| TASK/FOLLOWER_REMOVED | a follower is removed from a task\n| TASK/REOPENED \
\ | a closed task is reopened |\n"
- name: Customer Lookup
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: Versioning
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](#backwards-compatible-changes)**),\nor result in a new version that you will need to\
\ integrate with afresh (i.e. **[non-backwards compatible changes](#non-backwards-compatible-changes)**).\n\n## URL Path\
\ Versioning\n\nThe 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:\n\n https://organization.gladly.com/api/v{major-version-number}/{resource\
\ path}\n\n## Backwards Compatible Changes\n\nFor the most part, changes to the API will be backwards compatible, such\
\ as adding resources, additional fields to response objects,\nnew value types for enums, or expanding a validation constraint\
\ to be more accepting.\n\nEnsure your client can gracefully handle or ignore unfamiliar fields and values so it continues\
\ to operate smoothly over the lifespan of an API version.\n\n## Non-Backwards Compatible Changes\n\nVersions will be\
\ upleveled when a non-backwards compatible change occurs. This should not happen often, but can occur in the case of:\n\
- a field being removed from an object\n- a resource path no longer being supported\n- changing the type of a field\n\
- adding a new required parameter for a resource\n- constricting the validation parameters for a request\n\nThese will\
\ only occur when absolutely necessary and a summary of the changes from version to version can be viewed in the release\
\ notes.\nPrevious versions will be supported for a period of time before being removed after providing ample advanced\
\ notice.\n"
- name: Error Handling
description: "Wherever possible, Gladly uses standard HTTP status codes to signal the success or failure of a call.\nGenerally\
\ speaking, `2xx` statuses indicate success, `3xx` statuses indicate the client must take further action such as redirection,\n\
`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).\n\n## Common Status Codes\n\n| HTTP Status | Description |\n| -----------\
\ | ------------------------------------------------- |\n| 200 | Success with results in response body \
\ |\n| 201 | Resource created |\n| 204 | Success with empty response\
\ body |\n| 301 | The resource location has moved |\n| 400 | API usage\
\ error |\n| 401 | Authentication not provided |\n| 403\
\ | User does not have persmission to access resource |\n| 404 | Resource is not found \
\ |\n| 429 | Rate limit reached |\n\n## Programmatic Remediation\n\
In the case of a `400` response, there will be a structured list of `error` objects that will provide information to correct\
\ the error.\nThe error object will contain a `code` to describe the problem.\n\nThe most common codes are:\n\n| Code\
\ | Description |\n| ------------ | -------------------------------------- |\n| blank\
\ | Presence error |\n| invalid | Format error |\n| moved\
\ | This resource is now located elsewhere |\n| not_a_number | Value not numeric error |\n| present\
\ | Absence error |\n| taken | Uniqueness error |\n| too_long\
\ | Exceeds permissible length error |\n| wrong_length | Length is not equal to expected error |\n\nRefer to\
\ the errors section of each endpoint for more information.\n\nExample:\n\n {\"errors\":[{\"code\":\"blank\",\"detail\"\
:\"one of emailAddress, phoneNumber must be present\"}]}\n"
- name: Rich Content
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: Launching Soon
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: Rate Limit
description: "The number of requests for an **[organization](/rest/#tag/Organization)** 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](#tag/Reports) 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"
x-tagGroups:
- name: REST API
tags:
- Agents
- Public Answer
- Answer Management
- Audiences
- Business Hours
- Communications
- Conversations
- Customers
- Events
- Export
- Freeform Topics
- Inboxes
- Organization
- Proactive Conversations
- Reports
- Tasks
- Teams
- User Identity
- Topics
- Webhooks
- name: Webhooks
tags:
- Summary
- Payloads
- name: Lookup API
tags:
- Customer Lookup
- name: Resources
tags:
- Versioning
- Error Handling
- Rate Limit
- Rich Content
- Launching Soon
paths:
/api/v1/communications/sms:
post:
tags:
- Communications
summary: Send SMS
description: "To send an SMS message to a customer specified by a mobile phone number.\n\nGladly can send outbound SMS\
\ messages globally. By default, your organization is set up to only allow access to your home country. To send SMS\
\ messages to other countries, please contact [Gladly Support](https://help.gladly.com/implementation/docs/filing-a-support-issue)\
\ with a P4 designation.\n\nPlease be aware that:\n- Any automated outbound text messages **must** comply with carrier\
\ [acceptable use policies](https://help.gladly.com/docs/sms-compliance-requirements) (e.g.: if sending automated\
\ messages about order status, make sure customers can explicitly opt-in to text messages), including registering\
\ your SMS use cases carriers. \n- Text messages send in [segments](https://help.gladly.com/v1/docs/en/voice-and-sms-phone-number-costs)\
\ and you pay per segment. We highly recommend using the [segment calculator](https://twiliodeved.github.io/message-segment-calculator/)\
\ when crafting automated outbound text messages. \n- Each type of phone number has a [Message Segments per Second\
\ limit](https://support.twilio.com/hc/en-us/articles/115002943027-Understanding-Twilio-Rate-Limits-and-Message-Queues).\n"
operationId: sendSMS
requestBody:
description: SMS to send
content:
application/json:
schema:
title: SMS request body
required:
- customer
- from
- body
type: object
properties:
customer:
title: customer with mobile number
required:
- mobileNumber
type: object
properties:
mobileNumber:
$ref: '#/paths/~1api~1v1~1communications~1sms/post/requestBody/content/application~1json/schema/properties/from'
from:
title: mobile number
type: string
example: '+14152223316'
body:
title: SMS message
type: string
example: hello, this is an SMS message!
example:
customer:
mobileNumber: '+14152223000'
from: '+14152223316'
body: hello, this is a sample SMS message!
required: true
responses:
'200':
description: the customer and conversation item ID
content:
application/json:
schema:
type: object
properties:
customerId:
type: string
description: customer ID
example: gHufx-U3QqOmhvFuViceTw
conversationItemId:
type: string
description: conversation item ID of the SMS
example: pOVVdzweSumI4bFxjlT8LA
'400':
description: Invalid field(s) in request body
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
/api/v1/communications/email:
post:
tags:
- Communications
summary: Send Email
description: 'Used to send an email messages to a customer specified by an email address.
Any items created using this API will not be considered part of a conversation, and are **non-routable** and **non-searchable**
aside from the email address specified as part of the payload.
'
operationId: sendEmail
requestBody:
description: Email to send
content:
application/json:
schema:
title: Email request body
required:
- to
- from
- subject
- body
type: object
properties:
to:
description: Email addresses to send the email to. Currently, only one email address is supported. The email
address and name will be used to find or create the customer.
type: array
items:
type: object
properties:
email:
type: string
name:
type: string
example:
email: jane.doe@example.com
name: Jane Doe
from:
description: Email address to send the email from. This must be a configured email address in your organization.
type: string
example: no-reply@gladly.com
subject:
type: string
description: Subject of the email. Must be less than 1000 characters.
example: This is a sample email message!
body:
description: Content of the email.
type: object
properties:
html:
type: string
description: HTML content of the email.
example: This is a sample email message!
Best regards,
The Support Team
This is a sample email message!
Best regards,
The Support Team
This is a sample email message!
Best regards,
The Support Team
AVAILABLE : Recording is available for download
DELETED : Recording was deleted by the user
ERROR : An error occurred while recording.
Please contact Gladly Support Team'
enum:
- AVAILABLE
- DELETED
- ERROR
recordingUrl:
type: string
description: URL to retrieve media for the phone call recording in single-channel 32-kbps MP3 format.
Present if recording is “AVAILABLE”
recordingDuration:
type: integer
description: Duration of the phone call recording in seconds. Present if recording is “AVAILABLE”
example: 44
recordingSummary:
title: Recording Summary
description: Summary of the voice recording
type: object
properties:
status:
type: string
description: 'Status of the voice recoding summary.
FAILED : An error occurred while trying
to summarize a voice recording
READY : Recording summary is available
PENDING :
Trying to summarize a voice recording
REDACTED : An associated recording has been deleted'
enum:
- FAILED
- READY
- PENDING
- REDACTED
example: READY
summary:
type: string
description: Voice recording summary text
example: The customer calls to exchange an item. The representative asks for the customer's
details and explains that the return process is different for each situation. The customer
decides to reorder the correct size and thanks the representative for their help.
language:
type: string
description: Language
example: en
- title: SMS Message
description: A message sent via SMS
type: object
required:
- type
- from
- to
- content
properties:
type:
type: string
enum:
- SMS
from:
type: string
format: E.164
description: phone number of SMS sender
example: '+14153335555'
to:
type: string
format: E.164
description: phone number of SMS receiver
example: '+12149897676'
content:
type: string
description: text of the SMS message
example: I haven't received my order yet. Can you check on the status?
attachments:
type: array
description: attachments to the message
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'
- title: Topic Change
description: Record of an agent applying or removing a topic from the conversation
type: object
required:
- type
properties:
type:
type: string
enum:
- TOPIC_CHANGE
addedTopicIds:
type: array
description: ids of topics added to the conversation
items:
type: string
example: uu4t00vITaKQ3bVjU2UrGQ
removedTopicIds:
type: array
description: ids of topics removed from the conversation
items:
type: string
example: uu4t00vITaKQ3bVjU2UrGQ
- title: Voice AI Message
description: A spoken message exchanged between a customer and Gladly's voice AI during a voice AI session.
The item's `sessionId` identifies the voice AI session.
type: object
required:
- type
- companyNumber
- body
properties:
type:
type: string
enum:
- VOICE_AI_MESSAGE
customerNumber:
type: string
format: E.164
description: Phone number of the customer participating in the voice AI session
example: '+14153335555'
companyNumber:
type: string
format: E.164
description: Phone number the customer dialed to reach the voice AI session
example: '+12149897676'
body:
type: string
description: Text of the spoken message
example: Thanks for calling. How can I help you today?
status:
type: string
description: "Delivery status of a voice AI message spoken to the customer:\n * `PLAYED` - the\
\ message was played to the customer in full\n * `INTERRUPTED` - the customer interrupted the\
\ message before it finished playing\n"
enum:
- PLAYED
- INTERRUPTED
example: PLAYED
- title: Voicemail
description: Record of a voicemail left by customer in Gladly
type: object
required:
- type
properties:
type:
type: string
enum:
- VOICEMAIL
startedAt:
description: Start time of the voicemail
type: string
format: RFC3339
example: '2020-03-15T06:13:00.125Z'
recordingStatus:
type: string
description: 'Status of the voicemail recording
AVAILABLE : Recording is available for download
DELETED : Recording was deleted by the user
ERROR : An error occurred while recording.
Please contact Gladly Support Team'
enum:
- AVAILABLE
- DELETED
- ERROR
recordingUrl:
type: string
description: URL to retrieve media for the voicemail in single-channel 32-kbps MP3 format. Present
if recording status is “AVAILABLE”
recordingDuration:
type: integer
description: Duration of the voicemail in seconds. Present if recording status is “AVAILABLE”
example: 44
recordingSummary:
$ref: '#/paths/~1api~1v1~1conversation-items~1%7BitemId%7D/get/responses/200/content/application~1json/schema/properties/content/oneOf/6/properties/recordingSummary'
- title: WhatsApp Message
description: ''
type: object
required:
- type
- content
properties:
type:
type: string
enum:
- WHATSAPP
content:
type: string
description: text of the message
example: I love your brand! Do you have a loyalty program?
attachments:
type: array
description: attachments to the message
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'
- title: Instagram Message
description: ''
type: object
required:
- type
- content
properties:
type:
type: string
enum:
- INSTAGRAM_DIRECT
content:
type: string
description: text of the message
example: I love your brand! Do you have a loyalty program?
attachments:
type: array
description: attachments to the message
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'
- title: Twitter Message (decommissioned as of 04/20/23 but can still be retrieved)
description: ''
type: object
required:
- type
- content
properties:
type:
type: string
enum:
- TWITTER
content:
type: string
description: text of the message
example: I love your brand! Do you have a loyalty program?
'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
description: 'To delete an item.
Please note only items of type **CUSTOMER_ACTIVITY** may be deleted by this API.
'
operationId: deleteItem
parameters:
- in: path
name: itemId
schema:
type: string
required: true
description: 'Id of the item to be deleted.
'
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
description: 'Returns the media file associated with the conversation item
'
operationId: getMedia
parameters:
- in: path
name: itemId
description: 'id of the conversation item
'
schema:
type: string
example: pOVVdzweSumI4bFxjlT8LA
required: true
responses:
'200':
description: The media file associated with the conversation item
content:
audio/mpeg:
schema:
type: string
format: binary
description: Single channel 32-kbps MP3 audio file
'404':
description: An item with the given id could not be found
/api/v1/conversation-items/{itemId}/voice-transcript:
get:
tags:
- Conversations
summary: Get Voice Transcript
description: 'Returns a transcript of a phone call or a voicemail
'
operationId: getVoiceTranscript
parameters:
- in: path
name: itemId
description: 'id of the conversation item
'
schema:
type: string
example: pOVVdzweSumI4bFxjlT8LA
required: true
responses:
'200':
description: The voice transcript of a phone call or a voicemail
content:
application/json:
schema:
title: Voice Transcript
description: Transcript of a voice recording
type: object
properties:
paragraphs:
type: array
description: Paragraphs
items:
description: Paragraph
type: object
properties:
transcript:
type: string
description: Transcript text
example: Hello! How are you doing today?
speaker:
type: integer
description: Speaker number
example: 0
startTime:
type: number
description: Start time of the paragraph (in seconds from the beginning of the recording)
example: 2.48
endTime:
type: number
description: End time of the paragraph (in seconds from the beginning of the recording)
example: 6.1
customerId:
type: string
description: Customer associated with the voice transcript
example: AloLvEkzQlqc7c4kyYQY1A
numberOfSpeakers:
type: integer
description: Number of speakers
example: 1
language:
type: string
description: Language
createdAt:
type: string
format: RFC3339 with millis
description: Time the voice transcript was created
example: '2024-05-15T14:09:23.000Z'
updatedAt:
type: string
format: RFC3339 with millis
description: Time the voice transcript was updated
example: '2024-05-15T14:19:23.000Z'
'404':
description: A transcript with the given id could not be found
/api/v1/conversation-items/{itemId}/attachments/{attachmentId}:
get:
tags:
- Conversations
summary: Get Attachment
description: 'Returns a redirect to the URL of the specified attachment on a conversation item.
The response is a `303 See Other` redirect. Follow the redirect to download the attachment content.
Attachments are available on conversation items with content types that support them, such as emails, chat messages,
SMS messages, and custom channel messages.
'
operationId: getAttachment
parameters:
- in: path
name: itemId
schema:
type: string
example: pOVVdzweSumI4bFxjlT8LA
required: true
description: 'Id of the conversation item that contains the attachment.
'
- in: path
name: attachmentId
schema:
type: string
example: dGhpcyBpcyBhbiBhdHRhY2htZW50
required: true
description: 'Id of the attachment to retrieve.
'
responses:
'303':
description: Redirect to the attachment URL
headers:
Location:
schema:
type: string
description: 'URL to download the attachment content.
'
'400':
description: The conversation item content does not contain attachments
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
- code: invalid
detail: conversation item content does not contain attachments
'404':
description: The conversation item or attachment could not be found
/api/v1/customers/{customerId}/conversation-items:
post:
tags:
- Conversations
summary: Create Item for Customer
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.
'
operationId: createCustomerItem
parameters:
- in: path
name: customerId
schema:
type: string
required: true
description: 'Id of the customer associated with this item.
You can look up the id using the [Find customers](index.html#tag/Customers) API.
'
requestBody:
description: Conversation Item to create
content:
application/json:
schema:
title: Conversation Item To Create
required:
- content
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
content:
$ref: '#/paths/~1api~1v1~1conversation-items/post/requestBody/content/application~1json/schema/properties/content'
examples:
Customer Activity:
summary: Example of a Customer Activity
value:
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
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:
schema:
type: string
example: https://example.gladly.com/api/v1/customers/TX6f82W4S_ayp11kP4dhrQ/conversation-items
description: Location of the new customer id to use
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
description: 'To delete an item.
Please note only items of type **CUSTOMER_ACTIVITY** may be deleted by this API.
'
operationId: deleteCustomerItem
parameters:
- in: path
name: customerId
schema:
type: string
required: true
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: itemId
schema:
type: string
required: true
description: 'Id of the item to be deleted.
'
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
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.
The response can be filtered by session using the optional `sessionId` query parameter.
'
operationId: getConversationItems
parameters:
- in: path
name: conversationId
schema:
type: string
required: true
description: Id of the conversation to get the timeline for
example: 9BcE2O0DQ2ynGHRmk9FeoA
- in: query
name: sessionId
schema:
type: string
required: false
description: Return only items whose `sessionId` matches the given value.
example: 5k04bYuTRGqyT6uoSQfWVA
responses:
'200':
description: The items on the conversation timeline
content:
application/json:
schema:
title: Conversation Items
type: array
items:
$ref: '#/paths/~1api~1v1~1conversation-items~1%7BitemId%7D/get/responses/200/content/application~1json/schema'
examples:
Conversation Items:
summary: Example of conversation items response
value:
- 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: Rk7dLm2xTXqNwZp8vB3YeA
conversationId: 9BcE2O0DQ2ynGHRmk9FeoA
customerId: OOrlNMXeS72gs_WEX2TtMg
timestamp: '2019-07-01T11:46:50.01Z'
initiator:
id: SIDEKICK_V2
type: SYSTEM
content:
type: CHAT_MESSAGE
sessionId: 5k04bYuTRGqyT6uoSQfWVA
content: Hello! I can help you with upgrading your account. What plan are you interested in?
- 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_WEX2TtMg
type: CUSTOMER
responder:
id: WmeA3Y51Q5ayCAaZ1AotIA
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: WmeA3Y51Q5ayCAaZ1AotIA
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: VnL3kQ8zSPmW9rXpA2fYbA
conversationId: 9BcE2O0DQ2ynGHRmk9FeoA
customerId: OOrlNMXeS72gs_WEX2TtMg
sessionId: 8K2mX9nRTyWv4bQzLpH5jA
timestamp: '2019-07-02T08:13:02.450Z'
initiator:
id: SIDEKICK_V2
type: SYSTEM
content:
type: VOICE_AI_MESSAGE
customerNumber: '+14153335555'
companyNumber: '+12149897676'
body: Thanks for calling. How can I help you today?
status: PLAYED
- 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 Topics to Conversation
description: 'Adds a list of topics to the conversation. If a topic being added already exists on the conversation,
that topic is ignored.
'
operationId: addTopicToConversation
parameters:
- in: path
name: conversationId
schema:
type: string
required: true
description: 'Id of the conversation.
'
requestBody:
content:
application/json:
schema:
title: List of Conversation Topics to Add
required:
- topicIDs
type: object
properties:
topicIds:
type: array
example:
- pOVVdzweSumI4bFxjlT8LA
items:
type: string
description: Topic Ids to be added to the conversation.
examples:
Conversation Topic:
summary: Example of a 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 From Conversation
description: 'Delete a topic from a conversation.
'
operationId: deleteTopicFromConversation
parameters:
- in: path
name: conversationId
schema:
type: string
required: true
description: 'Id of the conversation.
'
- in: path
name: topicId
schema:
type: string
required: true
description: 'Id of topic to be deleted from conversation.
'
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
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:
- in: path
name: customerId
schema:
type: string
required: true
description: 'Id of the customer.
'
- in: path
name: conversationId
schema:
type: string
required: true
description: 'Id of the conversation.
'
requestBody:
content:
application/json:
schema:
title: List of Conversation Freeform Topics to Add or Remove
required:
- content
type: object
properties:
body:
type: string
items:
type: object
description: Freeform topics that need to be added or removed from a conversation
examples:
Custom Attributes:
summary: Example of a Conversation Freeform Topic Add or Remove
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
description: Adds note to an existing conversation.
operationId: addNoteToConversation
parameters:
- in: path
name: conversationId
schema:
type: string
required: true
description: 'Id of the conversation.
'
requestBody:
content:
application/json:
schema:
title: Content of note to add
required:
- content
type: object
properties:
body:
type: string
description: Plain text or [rich content ](#tag/Rich-Content) of the note.
example: Customer has requested more information about our loyalty program.
examples:
Conversation Note:
summary: Example of a 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
description: 'Returns the note with the provided conversation and note id.
'
operationId: getNoteFromConversation
parameters:
- in: path
name: conversationId
description: 'id of the conversation
'
schema:
type: string
example: pOVVdzweSumI4bFxjlT8LA
required: true
- in: path
name: noteId
description: 'id of the note
'
schema:
type: string
example: aOVVdzweSumI4bFxjlT8LA
required: true
responses:
'200':
description: Conversation note
content:
application/json:
schema:
title: Conversation Note
type: object
required:
- id
- customerId
- content
- timestamp
properties:
id:
type: string
description: the id of the item
example: pOVVdzweSumI4bFxjlT8LA
customerId:
type: string
description: the id of the customer profile that this item belongs to
example: gHufx-U3QqOmhvFuViceTw
conversationId:
type: string
description: id of the conversation the item is part of if it is within one
example: PmDVUfWfRjKuwb4VgA2zEA
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:
$ref: '#/paths/~1api~1v1~1conversation-items/post/responses/200/content/application~1json/schema/properties/responder'
content:
title: Note
description: ''
type: object
required:
- type
properties:
type:
type: string
enum:
- CONVERSATION_NOTE
body:
type: string
description: text of the note
example: Customer has requested more information about our loyalty program.
attachments:
type: array
description: attachments to the message
items:
type: object
properties:
id:
type: string
description: ID of the attachment
example: pOVVdzweSumI4bFxjlT8LA
contentType:
type: string
description: Content type of the attachment
example: image/png
filename:
type: string
description: Filename of the attachment
example: attachment-1.png
fileSize:
type: integer
description: File size of the attachment in bytes
example: 1024
'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
description: Sends a response to a conversation item. If no agent is assigned to the conversation, the conversation
is assigned to the API User who made this call.
operationId: replyToMessage
parameters:
- in: path
name: itemId
description: 'id of the conversation item
'
schema:
type: string
example: pOVVdzweSumI4bFxjlT8LA
required: true
requestBody:
content:
application/json:
schema:
title: Message
description: Message that can be sent in Gladly
type: object
required:
- content
properties:
content:
title: Message content
oneOf:
- title: Email Message Content
description: The content of the email message
type: object
required:
- type
- body
properties:
type:
type: string
enum:
- EMAIL
body:
type: string
description: HTML message that can be added to an email
example: Customer service is being reinvented by Gladly
bodyPlain:
type: string
description: Plain text message that can be added to an email
example: Customer service is being reinvented by Gladly
- title: Chat Message Content
oneOf:
- title: Message Content
description: The content of the chat message
type: object
required:
- type
- body
properties:
type:
type: string
enum:
- CHAT_MESSAGE
messageType:
type: string
enum:
- TEXT
body:
type: string
description: Plain text message
example: Customer service is being reinvented by Gladly
- title: QuickReply Request Content
description: The content of chat QuickReply request
type: object
required:
- type
- body
- messageType
- messageData
properties:
type:
type: string
enum:
- CHAT_MESSAGE
messageType:
type: string
enum:
- QUICK_REPLY_REQUEST
body:
type: string
description: Plain text message
example: What can I help you with?
messageData:
type: object
description: QuickReply request data
required:
- options
properties:
options:
type: array
title: Options
description: The options the user can choose from, the number of options must be greater or
equal to one and less or equal to 10.
items:
type: object
title: Option
required:
- id
- label
properties:
id:
type: string
title: Id
description: Id of this option, must be unique in the request and only contain alphanumeric
characters (a-z, A-Z, 0-9), hyphen or underscore
label:
type: string
title: Label
description: Text label of the option that will be presented to the user (max length 50
characters)
- title: Facebook Message Content
description: The content of the facebook message
type: object
required:
- type
- body
properties:
type:
type: string
enum:
- FACEBOOK_MESSAGE
body:
type: string
description: Plain text message
example: Customer service is being reinvented by Gladly
- title: Instagram Direct Message Content
description: The content of the Instagram Direct message
type: object
required:
- type
- body
properties:
type:
type: string
enum:
- INSTAGRAM_DIRECT
body:
type: string
description: Plain text message
example: Customer service is being reinvented by Gladly
- title: SMS Message Content
description: The content of the sms message
type: object
required:
- type
- body
properties:
type:
type: string
enum:
- SMS
body:
type: string
description: Plain text message
example: Customer service is being reinvented by Gladly
- title: Twitter Direct Message Content (decommissioned as of 04/20/2023)
description: The content of the twitter direct message
type: object
required:
- type
- body
properties:
type:
type: string
enum:
- TWITTER
body:
type: string
description: Plain text message
example: Customer service is being reinvented by Gladly
- title: WhatsApp Message Content
description: The content of the WhatsApp message
type: object
required:
- type
- body
properties:
type:
type: string
enum:
- WHATSAPP
body:
type: string
description: Plain text message
example: Customer service is being reinvented by Gladly
examples:
Reply with email:
summary: Example of an email reply message
value:
content:
type: EMAIL
body: Hi!
Of course we can help with your issue!
bodyPlain: "Hi!\n We can definitely help you with that!"
Reply with chat message:
summary: Example of a chat message reply message
value:
content:
type: CHAT_MESSAGE
messageType: TEXT
body: Hi from chat!
Reply with chat quick reply:
summary: Example of a chat quick reply message
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:
summary: Example of a Facebook reply message
value:
content:
type: FACEBOOK_MESSAGE
body: Hi from Facebook Messenger!
Reply with instagram direct message:
summary: Example of an Instagram Direct reply message
value:
content:
type: INSTAGRAM_DIRECT
body: Hi from Instagram Direct!
Reply with sms message:
summary: Example of an SMS reply message
value:
content:
type: SMS
body: Hi from SMS!
Reply with twitter direct message (decommissioned as of 04/20/2023):
summary: Example of a Twitter reply message
value:
content:
type: TWITTER
body: Hi from Twitter Direct Messages!
Reply with whatsapp message:
summary: Example of a WhatsApp reply 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:
summary: Error trying to act on closed conversation
value:
errors:
- code: invalid
detail: you cannot reply to items in closed conversations
Empty type:
summary: Error trying to send a message with an empty type
value:
errors:
- code: blank
attr: content.type
Wrong type:
summary: Error trying to send a reply message to unsupported type
value:
errors:
- code: invalid
detail: type [VOICEMAIL] is not supported
Body too long:
summary: Error trying to send a message with too long content
value:
errors:
- code: too_long
attr: content.body
detail: content.body cannot be larger than 2048 characters
Not a customer message:
summary: Error trying to send reply to a message that was not from the customer
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
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.
'
operationId: redactContent
parameters:
- in: path
name: itemId
description: 'id of the conversation item
'
schema:
type: string
example: pOVVdzweSumI4bFxjlT8LA
required: true
requestBody:
content:
application/json:
schema:
description: The request body should be empty
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/tasks:
post:
operationId: createTaskAndCustomer
tags:
- Tasks
summary: Create Task
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:
required:
- body
- dueAt
- assignee
- customer
properties:
id:
maxLength: 50
type: string
description: Specifies the id of the task
example: pOVVdzweSumI4bFxjlT8LA
assignee:
title: Assignee
description: Inbox and Agent assignee for a Task
required:
- inboxId
properties:
inboxId:
type: string
description: Id of the inbox the task should be assigned to. You can look up the id in the Gladly UI.
example: NFpDZtfqhk2pI6fjaVDlFf
agentId:
type: string
description: Id of the agent the task should be assigned to. You can look up the id in the Gladly UI.
example: zGaHXjD4SR-moMR9LbULDa
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'
customer:
title: Customer Specification
description: Specifies the customer this 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'
responses:
'201':
description: task created
headers:
Location:
schema:
type: string
description: path to the created task
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
description: 'Add a task to an existing customer''s conversation timeline
'
operationId: createTask
parameters:
- in: path
name: customerId
schema:
type: string
required: true
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.
'
requestBody:
description: Create Task
content:
application/json:
schema:
title: Create Task
description: A task to be completed for a specific customer
required:
- body
- dueAt
- assignee
properties:
id:
maxLength: 50
type: string
description: Unique task id. Must be URL safe and under 50 characters. An id will be automatically generated
if one is not included.
example: pOVVdzweSumI4bFxjlT8LA
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'
responses:
'201':
description: task created
headers:
Location:
schema:
type: string
description: path to the created task
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
description: "Fetch all tasks for a customer.\n\nThe list is not paginated and will return at most 2000 tasks. The tasks\
\ are returned in descending order by timestamp. \nThe `Gladly-Limited-Data` header flag in the response will indicate\
\ if the customer has more tasks than returned. \n\nTo see and act on any newly created tasks, webhooks can\
\ be used to listen for task related events.\nTasks older than the limit can be viewed using the Task Export.\n"
operationId: getTasks
parameters:
- in: path
name: customerId
schema:
type: string
required: true
description: 'Id of the customer whose tasks you''d like to view.
'
- in: query
name: status
description: 'Fetch tasks with the provided status.
'
required: false
schema:
type: string
enum:
- OPEN
- CLOSED
responses:
'200':
description: Array of tasks
content:
application/json:
schema:
title: Tasks
type: array
items:
$ref: '#/paths/~1api~1v1~1tasks~1%7BtaskId%7D/get/responses/200/content/application~1json/schema'
'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
description: 'Update an existing task
'
operationId: updateTask
parameters:
- in: path
name: taskId
schema:
type: string
required: true
description: 'Id of the task that is to be updated
'
requestBody:
description: Task properties to create
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- OPEN
- CLOSED
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:
type: string
description: Due date of task
format: RFC3339 with millis
example: '2021-04-11T14:09:23.000Z'
assignee:
type: object
$ref: '#/paths/~1api~1v1~1tasks/post/requestBody/content/application~1json/schema/properties/assignee'
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
description: 'Get task
'
operationId: getTask
parameters:
- in: path
name: taskId
schema:
type: string
required: true
description: 'Id of the task requested
'
responses:
'200':
description: Returns requested task
content:
application/json:
schema:
title: Task
type: object
required:
- customerId
- content
- timestamp
properties:
id:
type: string
description: the id of the task
example: pOVVdzweSumI4bFxjlT8LA
customerId:
type: string
description: The Id of the customer profile to which the task is associated.
example: gHufx-U3QqOmhvFuViceTw
timestamp:
type: string
format: RFC3339
description: Time the task occurred
example: '2019-07-03T04:30:12.07Z'
createdBy:
allOf:
- $ref: '#/paths/~1api~1v1~1conversation-items/post/responses/200/content/application~1json/schema/properties/responder'
- example:
id: gHufx-U3QqOmhvFuViceTw
type: CUSTOMER
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'
status:
type: string
enum:
- OPEN
- CLOSED
'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
description: 'Create a comment on a task. Note that you can’t create comments on closed tasks.
'
operationId: createTaskComment
parameters:
- in: path
name: taskId
schema:
type: string
required: true
description: 'Id of the task that will be commented on.
'
requestBody:
description: Add comment to task
content:
application/json:
schema:
title: Task Comment Request
description: Add a comment to an open task.
type: object
required:
- agentId
- message
properties:
id:
maxLength: 50
type: string
description: Unique comment id. Must be URL safe and under 50 characters. An id will be automatically generated
if one is not included.
example: pOVVdzweSumI4bFxjlT8LA
agentId:
type: string
description: the id of the agent making the comment
example: dzweSumI4bFxjlT8LApOVV
comment:
maxLength: 10000
type: string
description: Comment body
example: Return call to customer
responses:
'201':
description: comment added
headers:
Location:
schema:
type: string
description: path to the created task
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
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.
'
operationId: getTaskComments
parameters:
- in: path
name: taskId
schema:
type: string
required: true
description: 'Id of the task comments are requested for.
'
responses:
'200':
description: All comments that belong to task
content:
application/json:
schema:
title: Task Comments
type: array
items:
$ref: '#/paths/~1api~1v1~1tasks~1%7BtaskId%7D~1comments~1%7BcommentId%7D/get/responses/200/content/application~1json/schema'
'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
description: 'Get task comment.
'
operationId: getTaskComment
parameters:
- in: path
name: taskId
schema:
type: string
required: true
description: 'Task id
'
- in: path
name: commentId
schema:
type: string
required: true
description: 'Comment id
'
responses:
'200':
description: Returns task comment
content:
application/json:
schema:
title: Task Comment
type: object
properties:
id:
type: string
description: The id of the comment.
example: pOVVdzweSumI4bFxjlT8LA
agentId:
type: string
description: The id of the agent who owns the message.
example: dzweSumI4bFxjlT8LApOVV
comment:
type: string
description: Comment body.
example: Return call to customer.
taskId:
type: string
description: The id of the task being commented on.
example: dzweSumI4bFxjlT8LApOVV
createdAt:
type: string
format: RFC3339
example: '2020-03-15T06:13:00.125Z'
description: The time this comment was created
'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
description: 'Returns a custom attribute that matches the provided custom attribute id.
'
operationId: getCustomAttribute
parameters:
- name: customAttributeId
in: path
description: 'id of the custom attribute
'
required: true
schema:
type: string
example: 1grfSzATQLa334VDLCWc4A
responses:
'200':
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: id of the Custom Attribute
example: 1grfSzATQLa334VDLCWc4A
key:
type: string
description: key of the Custom Attribute
example: orderId
label:
type: string
description: label of the Custom Attribute
example: Order ID
deactivated:
type: boolean
description: whether the Custom Attribute is deactivated
example: true
createdAt:
type: string
format: RFC3339
description: time the Custom Attribute was created
example: '2020-05-20T15:00:00.000Z'
createdBy:
type: string
description: id of user who created the Custom Attribute
example: 7MRwXOeWRaGatwYCbBLLA
'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
description: 'Create a new customer with the supplied profile data.
'
operationId: createCustomer
requestBody:
required: true
description: Customer record to add.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1api~1v1~1customer-profiles~1%7BcustomerId%7D/patch/requestBody/content/application~1json/schema'
- type: object
properties:
id:
type: string
description: Unique customer id. Must be URL safe and under 50 characters. An id will be automatically
generated if one is not included
example: OOrlNMXeS72gs_WEX2TtMg
example:
id: OOrlNMXeS72gs_WEX2TtMg
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:
type: string
description: location of the created customer
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
description: "Find customers by searching by choosing **one** of the following identifiers as query parameters:\n\n\
```\n/api/v1/customer-profiles?phoneNumber=%2B14151234567\n```\n\nMax limit of 50 profiles returned, sorted by most\
\ recently updatedAt date descending. \n"
operationId: findCustomers
parameters:
- name: email
in: query
description: customer email address to search on.
schema:
type: string
example: customer@email.net
- name: externalCustomerId
in: query
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.
schema:
type: string
example: a21c1636-c622-48b7-bf6a-d9032645aa55
- name: phoneNumber
in: query
description: 'Phone number in E.164 format. The value should be URL escaped where `+` becomes `%2B`.
'
schema:
type: string
example: '+16505551987'
responses:
'200':
description: found customers
content:
application/json:
schema:
type: array
items:
$ref: '#/paths/~1api~1v1~1customer-profiles~1%7BcustomerId%7D/get/responses/200/content/application~1json/schema'
'400':
description: error finding customers
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
/api/v1/customer-profiles/{customerId}:
parameters:
- name: customerId
in: path
description: id of the customer
required: true
schema:
type: string
example: OOrlNMXeS72gs_WEX2TtMg
get:
tags:
- Customers
summary: Get Customer
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.
'
operationId: getCustomer
responses:
'200':
description: fetched customer
content:
application/json:
schema:
title: Customer
allOf:
- $ref: '#/paths/~1api~1v1~1customer-profiles/post/requestBody/content/application~1json/schema'
- type: object
properties:
createdAt:
type: string
format: RFC3339
description: Time the customer was created
example: '2019-02-21T07:15:18.07272933Z'
updatedAt:
type: string
format: RFC3339
description: Time of last update
example: '2019-02-21T19:50:23.486566336Z'
- type: object
properties:
externalCustomerIds:
type: object
description: 'Customer ID in your system of record for Customer Profiles linked to a Lookup Adaptor
installed after 05/12/21. If Customer Profile is linked to a Lookup Adaptor built prior to 05/12/21,
this field will not exist.
'
example:
ABC12345: '54321'
'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
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.
'
operationId: updateCustomer
requestBody:
required: true
description: JSON patch of customer profiles properties to insert or update.
content:
application/json:
schema:
title: Customer Profile
description: Customer profile
type: object
properties:
name:
type: string
description: Customer's name
example: Martha J Williams
image:
type: string
description: URL for an image that will appear as the customer's avatar
example: https://www.gladly.com/your-image.jpg
address:
type: string
description: Customer's street address
example: 563 Rigoberto Station Apt. 197
emails:
type: array
title: email addresses
description: Customer's email addresses
items:
type: object
required:
- original
properties:
normalized:
type: string
description: 'Customer''s email address in normalized form.
'
example: martha.williams@gmail.com
original:
type: string
description: 'Customer''s email address as entered or imported, only the addr-spec (per RFC8228) is
retained.
'
example: Martha.Williams@gmail.com
primary:
type: boolean
description: marks the customer's preferred email. at most one per customer.
default: false
example: false
phones:
type: array
title: phone numbers
description: Customer's phone numbers
items:
type: object
required:
- original
properties:
normalized:
type: string
format: E.164
description: normalized E.164 value for the phone number.
example: '+17244895501'
extension:
type: string
description: phone number extension.
example: '123'
original:
type: string
description: phone number as entered or imported.
example: '7244895501'
regionCode:
type: string
description: 'If set, the original is intepreted as a national number in this region.
If NOT set, the original must contian an E.164 number or it will be interpreted as a US number.
'
default: US
primary:
type: boolean
description: marks the customer's preferred phone.
default: false
smsPreference:
type: string
description: Enables sending SMS to a customer.
enum:
- 'ON'
- 'OFF'
- FORBIDDEN
example: 'OFF'
type:
type: string
description: 'Describes the usage of the device. Non-presense indicates unknown or non-specific OTHER
type.
'
enum:
- HOME
- MOBILE
- OFFICE
example: OFFICE
externalCustomerId:
type: string
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 will not exist and cannot be set.
example: a21c1636-c622-48b7-bf6a-d9032645aa55
customAttributes:
type: object
description: 'Organization-specific attributes from Customer system of record.
The shape of customAttributes is defined by the Customer Profile Definition. These are specific to a customer
and different from the Custom Attribute entity.
'
example:
membershipNumber: RQ564555333
membershipTier: gold
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'
delete:
tags:
- Customers
summary: Delete Customer
description: 'Delete a customer and all associated conversations.
All conversations associated with the customer must be closed before the customer can be deleted.
This operation is irreversible.
The user associated with the API token must have both Compliance Admin and API User roles.
'
operationId: deleteCustomer
responses:
'204':
description: customer was deleted
'400':
description: error deleting customer with open or waiting conversation
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
attr: conversation
code: invalid_state
detail: Unable to delete the profile. Please close any open or waiting conversations.
/api/v1/user-identity-jwt:
post:
tags:
- User Identity
summary: Create a User Identity JWT
description: "Create a User Identity JWT for a customer. The JWT is used to authenticate the customer with \n[Chat](https://developer.gladly.com/chat/).\
\ The JWT contains the customer identity information.\n"
operationId: createUserIdentityJWT
requestBody:
required: true
description: Customer Identity Information
content:
application/json:
schema:
title: Identity Object
type: object
properties:
identityType:
type: string
enum:
- EMAIL
- MOBILE_PHONE_NUMBER
description: The type of identity information
example: EMAIL
identity:
type: string
description: The identity information, the value depends on the identityType field. Needs to be a valid
email or phone number format ([E.164](https://en.wikipedia.org/wiki/E.164)).
example: test@example.com
example:
identityType: EMAIL
identity: test@example.com
responses:
'200':
description: customer created
content:
application/json:
schema:
type: object
properties:
token:
type: string
description: The JWT created
'400':
description: error creating JWT
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
/api/v1/orgs/{orgId}/answers-search?q=search+terms:
get:
tags:
- Public Answer
summary: Search Public Answers
description: 'Returns a list of answers that match the provided query string.
'
operationId: searchAnswers
parameters:
- name: orgId
in: path
description: 'id of your organization
You can look up the ID using the [Get organization](index.html#tag/Organization) API.
'
required: true
schema:
type: string
example: ihKsWxiZCDVtXg1iwVmT9Q
- name: q
in: query
description: search term
schema:
type: string
example: reset%20password
- name: lng
in: query
description: language code
schema:
type: string
example: en-us
- name: audienceId
in: query
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.
schema:
type: string
example: en-us
responses:
'200':
description: found answers
content:
application/json:
schema:
type: array
items:
properties:
id:
type: string
description: unique answer id
example: 1grfSzATQLa334VDLCWc4A
name:
type: string
description: Customer facing answer name
example: How to reset your password
/api/v1/orgs/{orgId}/answers?lng={lng}&audienceId={audienceId}:
get:
tags:
- Public Answer
summary: List Public Answers
description: 'Returns the first 1000 public answers sorted alphabetically by name.
'
operationId: listAnswers
parameters:
- name: orgId
in: path
description: 'id of your organization
You can look up the ID using the [Get organization](index.html#tag/Organization) API.
'
required: true
schema:
type: string
example: ihKsWxiZCDVtXg1iwVmT9Q
- name: lng
in: query
description: 'Language of the answers returned
Defaults to `en-us`
'
schema:
type: string
example: es-419
- name: audienceId
in: query
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.
'
schema:
type: string
example: ihKsWxiZCDVtXg1iwVmT9Q
responses:
'200':
description: answers
content:
application/json:
schema:
type: array
items:
$ref: '#/paths/~1api~1v1~1orgs~1%7BorgId%7D~1answers~1%7BanswerId%7D/get/responses/200/content/application~1json/schema'
/api/v1/orgs/{orgId}/help-center/{helpCenterId}/answer-titles?lng={lng}&audienceId={audienceId}:
get:
tags:
- Public Answer
summary: List Help Center Answer Titles
description: 'Returns an array of answers configured in Help Center sections with their ID and name
'
operationId: getAnswerTitles
parameters:
- name: orgId
in: path
description: 'id of your organization
You can look up the ID using the [Get organization](index.html#tag/Organization) API.
'
required: true
schema:
type: string
example: ihKsWxiZCDVtXg1iwVmT9Q
- name: helpCenterId
in: path
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
'
required: true
schema:
type: string
example: ihKsWxiZCDVtXg1iwVmT9Q
- name: lng
in: query
description: 'Language of the answers returned
Defaults to `en-us`
'
schema:
type: string
example: es-419
- name: audienceId
in: query
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.
'
schema:
type: string
example: ihKsWxiZCDVtXg1iwVmT9Q
responses:
'200':
description: answers
content:
application/json:
schema:
type: array
items:
properties:
id:
type: string
description: unique answer id
example: 1grfSzATQLa334VDLCWc4A
name:
type: string
description: Customer facing answer name
example: How to reset your password
/api/v1/orgs/{orgId}/answers/{answerId}:
get:
tags:
- Public Answer
summary: Get Public Answer
description: 'Returns the answer with the provided id.
'
operationId: getAnswer
parameters:
- name: orgId
in: path
description: 'id of your organization
You can look up the ID using the [Get organization](index.html#tag/Organization) API.
'
required: true
schema:
type: string
example: ihKsWxiZCDVtXg1iwVmT9Q
- name: answerId
in: path
description: id of the answer
required: true
schema:
type: string
example: 1grfSzATQLa334VDLCWc4A
- name: lng
in: query
description: language code
schema:
type: string
example: en-us
responses:
'200':
description: answer
content:
application/json:
schema:
properties:
id:
type: string
description: unique answer id
example: 1grfSzATQLa334VDLCWc4A
name:
type: string
description: Customer facing answer name
example: How to reset your password
bodyHtml:
type: string
description: Public answer content
example:
language:
type: string
description: Answer language
example: en-us
updatedAt:
type: string
format: RFC3339 with millis
description: Time the answer was last updated
example: '2023-05-22T10:00:00.000Z'
/api/v1/answers:
post:
tags:
- Answer Management
summary: Add Answer
description: 'Adds an answer to the list of answers.
'
operationId: addAnswer
requestBody:
content:
application/json:
schema:
properties:
id:
type: string
description: unique answer id - optional (a new id will be generated if not provided)
example: 1grfSzATQLa334VDLCWc4A
name:
type: string
description: Customer facing answer name
example: How to reset your password
description:
type: string
description: Answer description gives more information about the answer to the Agent and appears in Answers
Search when an Agent searches for an email or messaging answer. Only available for email and messaging
content types
example: This is my first answer
audienceIds:
type: array
items:
type: string
description: List of Audience IDs to be associated with the answer
example:
- audience-1
- audience-2
examples:
Sample Answer:
summary: Example of an Answer
value:
name: How to reset your password
description: This is my first answer
audienceIds:
- audience-1
- audience-2
responses:
'200':
description: Added answer
content:
application/json:
schema:
properties:
id:
type: string
description: answer id
example: 1grfSzATQLa334VDLCWc4A
name:
type: string
description: Customer facing answer name
example: How to reset your password
description:
type: string
description: Answer description (visible in the UI for only certain content types)
example: This is my first answer
audienceIds:
type: array
items:
type: string
description: List of Audience IDs associated with the answer
example:
- audience-1
- audience-2
createdAt:
type: string
format: RFC3339
description: Time the answer was added
example: '2024-06-13T15:16:29.894Z'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
id contains unsupported characters:
value:
errors:
- attr: id
code: invalid
detail: id contains unsupported characters
name cannot be blank or missing:
value:
errors:
- attr: name
code: blank
detail: name cannot be blank
name too long:
value:
errors:
- attr: name
code: too_long
detail: name cannot be longer than 500 characters
description too long:
value:
errors:
- attr: description
code: too_long
detail: description cannot be longer than 10000 characters
'409':
description: Specified id is in use
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
answer id already taken:
value:
errors:
- attr: id
code: taken
detail: answer id already taken
name already taken:
value:
errors:
- attr: name
code: taken
detail: duplicate answer name
/api/v1/answers/{answerId}:
get:
tags:
- Answer Management
summary: Get Answer
description: 'Returns the answer requested.
'
operationId: getAnswerById
parameters:
- name: answerId
in: path
description: id of the answer
required: true
schema:
type: string
example: 1grfSzATQLa334VDLCWc4A
responses:
'200':
description: answer
content:
application/json:
schema:
properties:
id:
type: string
description: answer id
example: 1grfSzATQLa334VDLCWc4A
name:
type: string
description: Customer facing answer name
example: How to reset your password
description:
type: string
description: Answer description (visible in the UI for only certain content types)
example: This is my first answer
audienceIds:
type: array
items:
type: string
description: List of Audience IDs associated with the answer
example:
- audience-1
- audience-2
updatedAt:
type: string
format: RFC3339
description: Time the answer was last modified
example: '2024-06-13T15:16:29.894Z'
createdAt:
type: string
format: RFC3339
description: Time the answer was added
example: '2024-06-13T15:16:29.894Z'
'404':
description: Answer does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
code: not_exist
detail: answer does not exist
patch:
tags:
- Answer Management
summary: Update Answer
description: 'Updates the answer with the provided id.
'
operationId: updateAnswer
parameters:
- name: answerId
in: path
description: id of the answer
required: true
schema:
type: string
example: 1grfSzATQLa334VDLCWc4A
requestBody:
content:
application/json:
schema:
properties:
name:
type: string
description: Customer facing answer name
example: How to reset your password
description:
type: string
description: Answer description gives more information about the answer to the Agent and appears in Answers
Search when an Agent searches for an email or messaging answer. Only available for email and messaging
content types
example: This is my first answer
audienceIds:
type: array
items:
type: string
description: List of Audience IDs to be associated with the answer. Updating this will replace the existing
set of audience IDs. The Audience API can be used to retrieve the audience IDs created for the org.
example:
- audience-1
- audience-2
examples:
Sample Answer:
$ref: '#/paths/~1api~1v1~1answers/post/requestBody/content/application~1json/examples/Sample%20Answer'
responses:
'204':
description: Answer updated
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
name already taken:
value:
errors:
- attr: name
code: taken
detail: duplicate answer name
name too long:
value:
errors:
- attr: name
code: too_long
detail: name cannot be longer than 500 characters
description too long:
value:
errors:
- attr: description
code: too_long
detail: description cannot be longer than 10000 characters
'404':
description: Answer does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
code: not_exist
detail: answer does not exist
delete:
tags:
- Answer Management
summary: Delete Answer
description: 'Deletes the answer with the provided id.
'
operationId: deleteAnswer
parameters:
- name: answerId
in: path
description: id of the answer
required: true
schema:
type: string
example: 1grfSzATQLa334VDLCWc4A
responses:
'204':
description: Answer deleted
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorsWithMeta'
examples:
answer associated with rules:
value:
errors:
- attr: answer
code: in_use
detail: answer is associated with rules
answer associated with help center:
value:
errors:
- code: in_use
detail: Public response used in Help Center 'help center name' Section 'section name'
meta:
helpCenterID: helpCenterId
sectionID: sectionId
snippetID: answerId
answer associated with thread:
value:
errors:
- attr: answer
code: in_use
detail: answer is associated with thread
'404':
description: Answer does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
code: not_exist
detail: answer does not exist
/api/v1/answers/{answerId}/languages/{language}/type/{type}:
get:
tags:
- Answer Management
summary: Get Answer Content
description: 'Returns the answer content requested by language and type.
'
operationId: getAnswerContentByLanguageAndType
parameters:
- name: answerId
in: path
description: id of the answer
required: true
schema:
type: string
example: 1grfSzATQLa334VDLCWc4A
- name: language
in: path
description: Language code according to ISO 639 format. The specified language must also be configured for the org.
required: true
schema:
type: string
example: en-us
- name: type
in: path
description: Type of answer. Must be one of `public`, `email`, `messaging`, or `reference`.
required: true
schema:
type: string
example: public
responses:
'200':
description: answerContent
content:
application/json:
schema:
properties:
answerId:
type: string
description: answer id
example: 1grfSzATQLa334VDLCWc4A
language:
type: string
description: Language of the answer content
example: en-us
type:
type: string
description: Answer content type
example: public
bodyHtml:
type: string
description: The body of the answer content
example: Public content
title:
type: string
description: Title of the answer content. Present for `public` type.
example: Reset Password
subject:
type: string
description: Subject line of the answer content. Present for `email` type.
example: 'Re: Your inquiry'
internal:
type: boolean
description: Whether the content is internal-only. Present for `reference` type.
example: false
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid language:
value:
errors:
- attr: language
code: invalid
detail: invalid language
language not configured:
value:
errors:
- attr: language
code: invalid
detail: language not configured for org
invalid type:
value:
errors:
- attr: type
code: invalid
detail: invalid type
'404':
description: Answer content does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
answer content does not exist:
value:
errors:
code: not_exist
detail: answer content does not exist
answer does not exist:
value:
errors:
code: not_exist
detail: answer does not exist
put:
tags:
- Answer Management
summary: Add or Update Answer Content
description: 'Adds or Updates the answer content for the specified answer by language and type.
'
operationId: addAnswerContentByLanguageAndType
parameters:
- name: answerId
in: path
description: id of the answer
required: true
schema:
type: string
example: 1grfSzATQLa334VDLCWc4A
- name: language
in: path
description: Language code according to ISO 639 format. The specified language must also be configured for the org.
required: true
schema:
type: string
example: en-us
- name: type
in: path
description: Type of answer. Must be one of `public`, `email`, `messaging`, or `reference`.
required: true
schema:
type: string
enum:
- public
- email
- messaging
- reference
example: public
requestBody:
description: 'The request body fields depend on the content type:
- **public**: `bodyHtml` (required), `title` (required)
- **email**: `bodyHtml` (required), `subject` (required)
- **messaging**: `bodyHtml` (required)
- **reference**: `bodyHtml` (required), `internal` (optional, defaults to false)
'
content:
application/json:
schema:
properties:
bodyHtml:
type: string
description: The body of the answer content. Required for all content types.
example: Public content
title:
type: string
description: Title of the answer content. Required for `public` type.
example: Reset Password
subject:
type: string
description: Subject line of the answer content. Required for `email` type.
example: 'Re: Your inquiry'
internal:
type: boolean
description: Whether the content is internal-only. Applicable to `reference` type.
example: false
examples:
Public Content:
summary: Example of public answer content
value:
bodyHtml: Navigate to Settings and click Reset Password.
title: How to reset your password
Email Content:
summary: Example of email answer content
value:
bodyHtml: Thank you for reaching out.
subject: 'Re: Your inquiry'
Messaging Content:
summary: Example of messaging answer content
value:
bodyHtml: Thanks for messaging us!
Reference Content:
summary: Example of reference answer content
value:
bodyHtml: Internal reference notes for agents.
internal: false
responses:
'200':
description: Added/Updated answer content
content:
application/json:
schema:
$ref: '#/paths/~1api~1v1~1answers~1%7BanswerId%7D~1languages~1%7Blanguage%7D~1type~1%7Btype%7D/get/responses/200/content/application~1json/schema'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
invalid language:
value:
errors:
- attr: language
code: invalid
detail: invalid language
language not configured:
value:
errors:
- attr: language
code: invalid
detail: language not configured for org
invalid type:
value:
errors:
- attr: type
code: invalid
detail: invalid type
'404':
description: Answer does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
code: not_exist
detail: answer does not exist
delete:
tags:
- Answer Management
summary: Delete Answer Content
description: 'Deletes the answer content for the specified answer by language and type.
'
operationId: deleteAnswerContentByLanguageAndType
parameters:
- name: answerId
in: path
description: id of the answer
required: true
schema:
type: string
example: 1grfSzATQLa334VDLCWc4A
- name: language
in: path
description: Language code according to ISO 639 format. The specified language must also be configured for the org.
required: true
schema:
type: string
example: en-us
- name: type
in: path
description: Type of answer. Must be one of `public`, `email`, `messaging`, or `reference`.
required: true
schema:
type: string
example: public
responses:
'204':
description: Answer content deleted
'400':
description: Bad Request
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/ErrorsWithMeta'
examples:
invalid language:
value:
errors:
- attr: language
code: invalid
detail: invalid language
language not configured:
value:
errors:
- attr: language
code: invalid
detail: language not configured for org
invalid type:
value:
errors:
- attr: type
code: invalid
detail: invalid type
type not implemented:
value:
errors:
- attr: type
code: invalid
detail: not implemented
answer associated with rules:
value:
errors:
- attr: answer
code: in_use
detail: answer is associated with rules
answer associated with help center:
value:
errors:
- code: in_use
detail: Public response used in Help Center 'help center name' Section 'section name'
meta:
helpCenterID: helpCenterId
sectionID: sectionId
snippetID: answerId
answer associated with thread:
value:
errors:
- attr: answer
code: in_use
detail: answer is associated with thread
'404':
description: Does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
answer content does not exist:
value:
errors:
code: not_exist
detail: answer content does not exist
answer does not exist:
value:
errors:
code: not_exist
detail: answer does not exist
/api/v1/agents:
get:
tags:
- Agents
summary: List Agents
description: 'Returns a list of agents.
'
operationId: getAgents
responses:
'200':
description: Agents
content:
application/json:
schema:
title: Agents
type: array
items:
$ref: '#/paths/~1api~1v1~1agents~1%7BagentId%7D/get/responses/200/content/application~1json/schema'
/api/v1/agents/{agentId}:
parameters:
- name: agentId
in: path
description: id of the agent
required: true
schema:
type: string
example: WmeA3Y51Q5ayCAaZ1AotIA
get:
tags:
- Agents
summary: Get Agent
description: 'Get an agent profile by their unique id.
'
operationId: getAgent
responses:
'200':
description: Agent
content:
application/json:
schema:
title: Agent
type: object
properties:
id:
type: string
description: Id of the agent
example: WmeA3Y51Q5ayCAaZ1AotIA
name:
type: string
description: First and last name of the agent
example: Amy Agent
emailAddress:
type: string
description: Agent's login email address
example: amy.agent@company.com
/api/v1/agents/{agentId}/call-recorder:
parameters:
- name: agentId
in: path
description: Gladly ID or Gladly email address of the agent
required: true
schema:
type: string
example: WmeA3Y51Q5ayCAaZ1AotIA OR agent@customer.com
get:
tags:
- Agents
summary: Get Agent CallRecorder
description: 'Get an agent call recording status.
'
operationId: getAgentCallRecording
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
description: 'Update an agent''s active call recording status. This API allows changing the `recording` property.
'
operationId: updateAgentCallRecording
requestBody:
required: true
description: JSON patch of CallRecorder
content:
application/json:
schema:
title: CallRecorder
type: object
properties:
agentId:
type: string
description: Id of the agent
example: WmeA3Y51Q5ayCAaZ1AotIA
customerId:
type: string
description: Id of the customer on the call, if the agent is on a call. If the agent is not on a call this
is omitted
example: ZcyobierQhucTS5GV1R2Fw
conversationItemId:
type: string
description: Id of the conversation item of the call, if the agent is on a call. If the agent is not on
a call this is omitted
example: g6UatsvAQC69AcDpOKF-yQ
recording:
type: boolean
description: If the call is currently being recorded or not
example: 'true'
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/audiences:
get:
tags:
- Audiences
summary: List Audiences
description: 'Returns a list of audiences.
'
operationId: getAudiences
responses:
'200':
description: Audiences
content:
application/json:
schema:
title: Audiences
type: array
items:
title: Audience
type: object
properties:
id:
type: string
description: Id of the audience
example: 3cIEsaYcQTSFfECpBhGL6Q
name:
type: string
description: name of the audience
example: Retale - USA
/api/v1/business-hours:
get:
tags:
- Business Hours
summary: List Business Hours
description: 'Returns a list of all business hours configurations for your organization.
'
operationId: getBusinessHours
responses:
'200':
description: Business hours
content:
application/json:
schema:
title: BusinessHoursList
type: array
items:
$ref: '#/paths/~1api~1v1~1business-hours/post/responses/201/content/application~1json/schema'
example:
- id: bh_WmeA3Y51Q5ayCAaZ1AotIA
version: 1
createdAt: '2024-01-15T09:00:00Z'
updatedAt: '2024-01-15T09:00:00Z'
name: Default Hours
primary: true
officeHours:
timezone: America/Los_Angeles
monday:
- start: 09:00
stop: '17:00'
tuesday:
- start: 09:00
stop: '17:00'
wednesday:
- start: 09:00
stop: '17:00'
thursday:
- start: 09:00
stop: '17:00'
friday:
- start: 09:00
stop: '17:00'
post:
tags:
- Business Hours
summary: Create Business Hours
description: 'Creates a new business hours configuration for your organization.
'
operationId: createBusinessHours
requestBody:
required: true
description: Business hours configuration to create
content:
application/json:
schema:
title: BusinessHoursCreateRequest
type: object
required:
- name
- officeHours
properties:
name:
type: string
description: Name of the business hours configuration (max 200 characters)
example: Default Hours
primary:
type: boolean
description: Whether this should be the primary business hours configuration
default: false
example: false
officeHours:
title: OfficeHours
type: object
required:
- timezone
properties:
timezone:
type: string
description: IANA timezone identifier (e.g., America/Los_Angeles)
example: America/Los_Angeles
monday:
type: array
description: Schedule blocks for Monday
items:
title: ScheduleBlock
type: object
required:
- start
- stop
properties:
start:
type: string
description: Start time in HH:MM format (24-hour)
pattern: ^([01]?[0-9]|2[0-3]):[0-5][0-9]$
example: 09:00
stop:
type: string
description: End time in HH:MM format (24-hour)
pattern: ^([01]?[0-9]|2[0-3]):[0-5][0-9]$
example: '17:00'
tuesday:
type: array
description: Schedule blocks for Tuesday
items:
$ref: '#/paths/~1api~1v1~1business-hours/post/requestBody/content/application~1json/schema/properties/officeHours/properties/monday/items'
wednesday:
type: array
description: Schedule blocks for Wednesday
items:
$ref: '#/paths/~1api~1v1~1business-hours/post/requestBody/content/application~1json/schema/properties/officeHours/properties/monday/items'
thursday:
type: array
description: Schedule blocks for Thursday
items:
$ref: '#/paths/~1api~1v1~1business-hours/post/requestBody/content/application~1json/schema/properties/officeHours/properties/monday/items'
friday:
type: array
description: Schedule blocks for Friday
items:
$ref: '#/paths/~1api~1v1~1business-hours/post/requestBody/content/application~1json/schema/properties/officeHours/properties/monday/items'
saturday:
type: array
description: Schedule blocks for Saturday
items:
$ref: '#/paths/~1api~1v1~1business-hours/post/requestBody/content/application~1json/schema/properties/officeHours/properties/monday/items'
sunday:
type: array
description: Schedule blocks for Sunday
items:
$ref: '#/paths/~1api~1v1~1business-hours/post/requestBody/content/application~1json/schema/properties/officeHours/properties/monday/items'
exceptions:
type: array
description: Schedule exceptions (e.g., holidays)
items:
title: ScheduleException
type: object
required:
- name
- start
- stop
properties:
name:
type: string
description: Name of the exception (e.g., 'New Year's Day')
example: New Year's Day
start:
type: string
format: date-time
description: Start datetime of the exception
example: '2024-01-01T00:00:00Z'
stop:
type: string
format: date-time
description: End datetime of the exception
example: '2024-01-02T00:00:00Z'
scheduleBlocks:
type: array
description: Optional schedule blocks during the exception period (empty for closed)
items:
$ref: '#/paths/~1api~1v1~1business-hours/post/requestBody/content/application~1json/schema/properties/officeHours/properties/monday/items'
example:
name: Weekend Support
primary: false
officeHours:
timezone: America/Los_Angeles
saturday:
- start: '10:00'
stop: '16:00'
sunday:
- start: '10:00'
stop: '16:00'
responses:
'201':
description: Business hours created
content:
application/json:
schema:
title: BusinessHours
type: object
properties:
id:
type: string
description: Unique identifier for the business hours configuration
example: bh_WmeA3Y51Q5ayCAaZ1AotIA
version:
type: integer
description: Version number for optimistic concurrency control
example: 1
createdAt:
type: string
format: date-time
description: Timestamp when the business hours were created
example: '2024-01-15T09:00:00Z'
updatedAt:
type: string
format: date-time
description: Timestamp when the business hours were last updated
example: '2024-01-15T09:00:00Z'
name:
type: string
description: Name of the business hours configuration
example: Default Hours
primary:
type: boolean
description: Whether this is the primary business hours configuration
example: true
officeHours:
$ref: '#/paths/~1api~1v1~1business-hours/post/requestBody/content/application~1json/schema/properties/officeHours'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
blankName:
summary: Name is required
value:
errors:
- attr: name
code: invalid
detail: name cannot be blank
missingTimezone:
summary: Timezone is required
value:
errors:
- attr: officeHours.timezone
code: blank
detail: Timezone is required
invalidTimezone:
summary: Invalid timezone
value:
errors:
- attr: officeHours.timezone
code: invalid
detail: Timezone is invalid
/api/v1/business-hours/{businessHoursId}:
parameters:
- name: businessHoursId
in: path
description: ID of the business hours configuration
required: true
schema:
type: string
example: bh_WmeA3Y51Q5ayCAaZ1AotIA
get:
tags:
- Business Hours
summary: Get Business Hours
description: 'Returns a single business hours configuration by its unique ID.
'
operationId: getBusinessHoursById
responses:
'200':
description: Business hours
content:
application/json:
schema:
$ref: '#/paths/~1api~1v1~1business-hours/post/responses/201/content/application~1json/schema'
'404':
description: Business hours not found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
- code: not_exist
detail: business hours does not exist
put:
tags:
- Business Hours
summary: Update Business Hours
description: 'Updates an existing business hours configuration. The `version` field must match the current version of
the business hours to prevent conflicting updates.
'
operationId: updateBusinessHours
requestBody:
required: true
description: Updated business hours configuration
content:
application/json:
schema:
title: BusinessHoursUpdateRequest
type: object
required:
- version
- name
- officeHours
properties:
version:
type: integer
description: Current version of the business hours (for optimistic concurrency)
example: 1
name:
type: string
description: Name of the business hours configuration (max 200 characters)
example: Updated Hours
primary:
type: boolean
description: Whether this should be the primary business hours configuration
example: false
officeHours:
$ref: '#/paths/~1api~1v1~1business-hours/post/requestBody/content/application~1json/schema/properties/officeHours'
example:
version: 1
name: Updated Business Hours
primary: false
officeHours:
timezone: America/New_York
monday:
- start: 08:00
stop: '18:00'
tuesday:
- start: 08:00
stop: '18:00'
wednesday:
- start: 08:00
stop: '18:00'
thursday:
- start: 08:00
stop: '18:00'
friday:
- start: 08:00
stop: '18:00'
responses:
'200':
description: Business hours updated
content:
application/json:
schema:
$ref: '#/paths/~1api~1v1~1business-hours/post/responses/201/content/application~1json/schema'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'404':
description: Business hours not found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
- code: not_exist
detail: business hours does not exist
'409':
description: Version conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
- code: version_outdated
detail: the version provided is outdated
delete:
tags:
- Business Hours
summary: Delete Business Hours
description: 'Deletes a business hours configuration. The primary business hours configuration cannot be deleted.
'
operationId: deleteBusinessHours
responses:
'204':
description: Business hours deleted
'400':
description: Cannot delete primary business hours
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
- code: invalid
detail: cannot delete primary business hours
'404':
description: Business hours not found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example:
errors:
- code: not_exist
detail: business hours does not exist
/api/v1/organization:
get:
tags:
- Organization
summary: Get Organization
description: 'Returns metadata about your organization.
'
operationId: getOrganization
responses:
'200':
description: Organization
content:
application/json:
schema:
title: Organization
type: object
properties:
id:
type: string
description: Id of your organization
example: ihKsWxiZCDVtXg1iwVmT9Q
loginDomain:
type: string
description: Email domain of your organization
example: organization.com
name:
type: string
description: Name of your organization
example: My Organization
timezone:
type: string
description: Timezone for your organization
example: America/Los_Angeles
gladlyUrl:
type: string
description: Url for your organization
example: https://organization.gladly.com
/api/v1/inboxes:
get:
tags:
- Inboxes
summary: List Inboxes
description: 'Returns a list of inbox metadata.
'
operationId: getInboxes
responses:
'200':
description: Inboxes
content:
application/json:
schema:
title: Inboxes
type: array
items:
$ref: '#/paths/~1api~1v1~1inboxes~1%7BinboxId%7D/get/responses/200/content/application~1json/schema'
/api/v1/inboxes/{inboxId}:
parameters:
- name: inboxId
in: path
description: id of the inbox
required: true
schema:
type: string
example: vZgCEQlDR6aQz_0HeWZ9_Q
get:
tags:
- Inboxes
summary: Get Inbox
description: 'Get the metadata for an inbox by its unique id.
'
operationId: getInbox
responses:
'200':
description: Inbox
content:
application/json:
schema:
title: Inbox
type: object
properties:
id:
type: string
description: Id of the inbox
example: vZgCEQlDR6aQz_0HeWZ9_Q
name:
type: string
description: Name of your inbox
example: Email Inbox
disabled:
type: boolean
description: Marks the inbox as disabled
example: false
/api/v1/teams:
get:
tags:
- Teams
summary: List Teams
description: 'Returns a list of teams.
'
operationId: getTeams
responses:
'200':
description: Teams
content:
application/json:
schema:
title: Teams
type: array
items:
$ref: '#/paths/~1api~1v1~1teams~1%7BteamId%7D/get/responses/200/content/application~1json/schema'
/api/v1/teams/{teamId}:
parameters:
- name: teamId
in: path
description: id of the team
required: true
schema:
type: string
example: ovg2jQCQS9ScsDkBxG-o2Q
get:
tags:
- Teams
summary: Get Team
description: 'Get a team by its unique id.
'
operationId: getTeam
responses:
'200':
description: Team
content:
application/json:
schema:
title: Team
type: object
properties:
id:
type: string
description: Id of the team
example: ovg2jQCQS9ScsDkBxG-o2Q
name:
type: string
description: Name of the team
example: Stay Advisors
description:
type: string
description: Description of the team
example: Team to answer customer questions about new bookings
agentIds:
type: array
description: Ids of the agents in the team
example:
- WmeA3Y51Q5ayCAaZ1AotIA
items:
type: string
/api/v1/topics:
get:
tags:
- Topics
summary: List Topics
description: 'Returns a list of Topics.
'
operationId: getTopics
responses:
'200':
description: Topics
content:
application/json:
schema:
title: Topics
type: array
items:
$ref: '#/paths/~1api~1v1~1topics~1%7BtopicId%7D/get/responses/200/content/application~1json/schema'
example:
summary: Topics
value:
- 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
post:
tags:
- Topics
summary: Add Topic
description: 'Add a Topic to the list of available Topics.
'
operationId: addTopic
requestBody:
description: Topic to create
content:
application/json:
schema:
title: Add Topic Request
required:
- name
properties:
id:
type: string
description: unique Topic id - optional (a new id will be generated if not provided)
example: uu4t00vITaKQ3bVjU2UrGQ
name:
type: string
description: Name of the Topic - must be unique
example: Order Returns
disabled:
type: boolean
description: If the Topic is not in use - optional, defaults to **false**
example: false
parentId:
type: string
description: id of parent Topic, if the Topic is nested under another topic - optional
example: ChefeoTHSlaIbKg57H5R9Q
responses:
'201':
description: Topic Created
headers:
Location:
schema: null
type: string
description: path to the created Topic
example: /api/v1/topics/RgEZdEiUSSK9DBjYFQLQyQ
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrors'
examples:
id contains unsupported characters:
value:
errors:
- attr: id
code: invalid
detail: id contains unsupported characters
name cannot be blank or missing:
value:
errors:
- attr: name
code: blank
detail: name cannot be blank
'409':
description: Topic contains conflicting values
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorsWithMeta'
examples:
topic with specified id already exists:
value:
errors:
- attr: id
code: taken
detail: the topic with specified id already exists
another topic already has this name:
value:
errors:
- attr: name
code: taken
detail: another topic already has this name
meta:
id: BgMCrCVbTrGhAeDTwIr44g
/api/v1/topics/{topicId}:
parameters:
- name: topicId
in: path
description: id of the Topic
required: true
schema:
type: string
example: uu4t00vITaKQ3bVjU2UrGQ
get:
tags:
- Topics
summary: Get Topic
description: 'Get a Topic by its unique id.
'
operationId: getTopic
responses:
'200':
description: Topic
content:
application/json:
schema:
title: Topic
type: object
properties:
id:
type: string
description: Id of the Topic
example: uu4t00vITaKQ3bVjU2UrGQ
name:
type: string
description: Name of the Topic
example: Order Returns
disabled:
type: boolean
description: If the Topic cannot be applied to Conversations, and is no longer in use
example: false
parentId:
type: string
description: If the Topic is nested under another topic, parentId is the Id of the parent topic. For more
information about topic hierarchy, please visit the [help docs](https://help.gladly.com/docs/en/principles-of-hierarchical-topics)
example: ChefeoTHSlaIbKg57H5R9Q
'404':
description: Given Topic id does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrors'
patch:
tags:
- Topics
summary: Update Topic
description: 'Update an existing Topic.
'
operationId: updateTopic
requestBody:
content:
application/json:
schema:
title: Update Topic Request
required:
- name
properties:
name:
type: string
description: Name of the Topic
example: Order Returns
disabled:
type: boolean
description: If the Topic is not in use
example: false
parentId:
type: string
description: id of parent Topic, if the Topic is nested under another topic - optional
example: ChefeoTHSlaIbKg57H5R9Q
responses:
'204':
description: Topic updated successfully
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
name cannot be blank or missing:
value:
errors:
- attr: name
code: blank
detail: name cannot be blank
'404':
description: Topic with the specified id does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrors'
example:
errors:
code: not_exist
detail: conversation topic [topicId] does not exist
'409':
description: Topic update contains conflicting values
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorsWithMeta'
examples:
another topic already has this name:
value:
errors:
- attr: name
code: taken
detail: another topic already has this name
meta:
id: BgMCrCVbTrGhAeDTwIr44g
/api/v1/export/schedules:
get:
tags:
- Export
summary: List Schedules
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).
'
operationId: findSchedules
responses:
'200':
description: found jobs
content:
application/json:
schema:
type: array
items:
title: Schedule
description: schedule
type: object
properties:
id:
type: string
description: Unique schedule id
example: vZgCEQlDR6aQz_0HeWZ9_Q
frequency:
type: string
description: Frequency for running export jobs
example: HOURLY
enum:
- HOURLY
- DAILY
type:
type: string
description: Type of export schedule
example: CONVERSATIONS
enum:
- CONVERSATIONS
nextStartAt:
type: string
format: RFC3339
description: Start time for the next export job
example: '2019-01-21T08:00:00.00Z'
updatedAt:
type: string
format: RFC3339
description: Time the schedule was last updated
example: '2019-01-21T07:15:18.07272933Z'
/api/v1/export/jobs:
get:
tags:
- Export
summary: List Jobs
description: "List all jobs for the organization in any status for the last 14 days. \n```\n/api/v1/export/jobs\n```\n\
\nYou can further filter the results by including query parameters for `status`, `startAt`, and `endAt`.\n```\n/api/v1/export/jobs?status=COMPLETED&startAt=2024-09-15T00:00:00.000Z&endAt=2024-09-16T00:00:00.000Z\n\
```\n"
operationId: findJobs
parameters:
- name: status
in: query
description: export job status to search on.
schema:
type: string
example: COMPLETED
enum:
- PENDING
- IN_PROGRESS
- COMPLETED
- FAILED
- name: startAt
in: query
description: 'Starting time to filter export jobs by. This is based on the `updatedAt` field which indicates when
the job was last updated. Cannot be more than 14 days ago. Default is 14 days ago.
The date should be in ISO 8601 format.
'
schema:
type: string
format: ISO 8601
example: '2024-09-15T00:00:00.000Z'
- name: endAt
in: query
description: 'Ending time to filter export jobs by. This is based on the `updatedAt` field which indicates when the
job was last updated. Cannot be before ''startAt'' or in the future. Default is now.
The date should be in ISO 8601 format.
'
schema:
type: string
format: ISO 8601
example: '2024-09-16T00:00:00.000Z'
responses:
'200':
description: found jobs
content:
application/json:
schema:
type: array
items:
$ref: '#/paths/~1api~1v1~1export~1jobs~1%7BjobId%7D/get/responses/200/content/application~1json/schema'
/api/v1/export/jobs/{jobId}:
parameters:
- name: jobId
in: path
description: id of the job
required: true
schema:
type: string
example: OOrlNMXeS72gs_WEX2TtMg
get:
tags:
- Export
summary: Get Job
description: 'Get a job by unique id.
'
operationId: getJob
responses:
'200':
description: fetched job
content:
application/json:
schema:
title: Export Job
description: Export job
type: object
properties:
id:
type: string
description: Unique job id
example: vZgCEQlDR6aQz_0HeWZ9_Q
scheduleId:
type: string
description: Schedule id the job belongs to
example: OOrlNMXeS72gs_WEX2TtMg
status:
type: string
description: Current status of the job
example: COMPLETED
enum:
- PENDING
- IN_PROGRESS
- COMPLETED
- FAILED
updatedAt:
type: string
format: RFC3339
description: Time the job was updated
example: '2019-02-21T07:15:19.07272933Z'
parameters:
title: JobParameters
description: Export job parameters
type: object
properties:
type:
type: string
description: Type of export job
example: CONVERSATIONS
enum:
- CONVERSATIONS
startAt:
type: string
format: RFC3339
description: Start time for the export query
example: '2019-01-21T07:15:18.07272933Z'
endAt:
type: string
format: RFC3339
description: End time for the export query
example: '2019-01-22T07:15:18.07272933Z'
files:
type: array
items:
type: string
default: []
description: An array of filenames associated with the job
example:
- agents.jsonl
- conversation_items.jsonl
- customers.jsonl
- topics.jsonl
links:
GetFilename:
operationId: getFile
parameters:
filename: $response.body#/id
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}`
'
'404':
description: job not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrors'
delete:
tags:
- Export
summary: Delete Job
description: 'Delete a job and all associated files. *Note*: job status must be `COMPLETED` or `FAILED` to be deleted.
'
operationId: deleteJob
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:
operationId: getFile
tags:
- Export
summary: Get File
parameters:
- name: jobId
in: path
description: id of the job
required: true
schema:
type: string
example: OOrlNMXeS72gs_WEX2TtMg
- name: filename
in: path
description: name of the file
required: true
schema:
type: string
example: agents.jsonl
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}
```
'
responses:
'200':
description: returns a file
content:
application/x-ndjson:
schema:
oneOf:
- title: agents.jsonl
type: array
items:
$ref: '#/paths/~1api~1v1~1agents~1%7BagentId%7D/get/responses/200/content/application~1json/schema'
- title: conversation_items.jsonl
allOf:
- title: Conversation Items
type: array
items:
title: Conversation Item
type: object
required:
- id
- customerId
- 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
conversationId:
type: string
description: id of the conversation the item is part of if it is within one
example: PmDVUfWfRjKuwb4VgA2zEA
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:
$ref: '#/paths/~1api~1v1~1conversation-items/post/responses/200/content/application~1json/schema/properties/responder'
content:
title: Conversation Item Content
oneOf:
- $ref: '#/paths/~1api~1v1~1conversation-items~1%7BitemId%7D/get/responses/200/content/application~1json/schema/properties/content/oneOf/0'
- $ref: '#/paths/~1api~1v1~1conversation-items~1%7BitemId%7D/get/responses/200/content/application~1json/schema/properties/content/oneOf/1'
- $ref: '#/paths/~1api~1v1~1conversation-items/post/requestBody/content/application~1json/schema/properties/content/oneOf/0'
- $ref: '#/paths/~1api~1v1~1conversation-items~1%7BitemId%7D/get/responses/200/content/application~1json/schema/properties/content/oneOf/3'
- $ref: '#/paths/~1api~1v1~1conversation-items~1%7BitemId%7D/get/responses/200/content/application~1json/schema/properties/content/oneOf/4'
- $ref: '#/paths/~1api~1v1~1conversations~1%7BconversationId%7D~1notes~1%7BnoteId%7D/get/responses/200/content/application~1json/schema/properties/content'
- $ref: '#/paths/~1api~1v1~1conversation-items~1%7BitemId%7D/get/responses/200/content/application~1json/schema/properties/content/oneOf/6'
- $ref: '#/paths/~1api~1v1~1conversation-items~1%7BitemId%7D/get/responses/200/content/application~1json/schema/properties/content/oneOf/7'
- $ref: '#/paths/~1api~1v1~1conversation-items~1%7BitemId%7D/get/responses/200/content/application~1json/schema/properties/content/oneOf/8'
- $ref: '#/paths/~1api~1v1~1conversation-items~1%7BitemId%7D/get/responses/200/content/application~1json/schema/properties/content/oneOf/10'
- $ref: '#/paths/~1api~1v1~1conversation-items~1%7BitemId%7D/get/responses/200/content/application~1json/schema/properties/content/oneOf/12'
- $ref: '#/paths/~1api~1v1~1conversation-items~1%7BitemId%7D/get/responses/200/content/application~1json/schema/properties/content/oneOf/11'
- title: customers.jsonl
type: array
items:
title: Customer Profile
description: Customer profile
type: object
properties:
name:
type: string
description: Customer's name
address:
type: string
description: Customer's street address
emailAddresses:
type: array
title: email addresses
description: Customer's email addresses
items:
type: string
phoneNumbers:
type: array
title: phone numbers
description: Customer's phone numbers
items:
type: string
externalCustomerId:
type: string
description: CCustomer 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 will not exist.
externalCustomerIds:
type: object
description: 'Customer ID in your system of record for Customer Profiles linked to a Lookup Adaptor
installed after 05/12/21. If Customer Profile is linked to a Lookup Adaptor built prior to 05/12/21,
this field will not exist.
'
example:
ABC12345: '54321'
- title: topics.jsonl
allOf:
- $ref: '#/paths/~1api~1v1~1topics/get/responses/200/content/application~1json/schema'
examples: null
'404':
description: file not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrors'
/api/v1/campaigns/{campaignId}/recipient-collections:
parameters:
- name: campaignId
in: path
description: id of the campaign to create a new recipient collection for
required: true
schema:
type: string
example: yQ16L_YURROhXAg3KzkuYQ
post:
tags:
- Proactive Conversations
summary: Create Recipient Collection for an Existing Proactive Campaign
description: 'Create a new recipient collection for an existing proactive campaign that will be contacted based on the
campaign settings.
You can locate the `campaignId` by navigating to the campaign in the dashboard and copying the `id` from the URL.
'
operationId: createRecipientCollection
requestBody:
content:
application/json:
schema:
title: Recipient Collection Create Request
description: Request payload for creating a new recipient collection
type: object
required:
- name
- startAfter
- recipients
properties:
name:
type: string
description: Name for recipient collection
example: Delivery reminders
startAfter:
type: string
format: RFC3339
description: The time after which the recipient collection should start processing
example: '2019-02-21T07:15:19.07272933Z'
endBefore:
type: string
format: RFC3339
description: The time before which the recipient collection should stop processing
example: '2019-02-21T07:15:19.07272933Z'
recipients:
type: array
items:
oneOf:
- title: Email Recipients
description: Email recipients for recipient collection request
type: object
required:
- customerName
- emailAddress
- timezone
properties:
customerName:
type: string
description: Name of customer
example: Jane Smith
emailAddress:
type: string
description: Email address for the customer
example: jane.smith@example.com
timezone:
type: string
description: Timezone the customer is located in. Supported timezones are those found in the IANA
timezone database.
example: America/Los_Angeles
- title: SMS Recipients
description: SMS recipients for recipient collection request
type: object
required:
- customerName
- phoneNumber
- timezone
properties:
customerName:
type: string
description: Name of customer
example: Jane Smith
phoneNumber:
type: string
description: Phone Number for the customer
example: (415) 555-1234
timezone:
type: string
description: Timezone the customer is located in. Supported timezones are those found in the IANA
timezone database.
example: America/Los_Angeles
- title: Voice Recipients
description: Voice recipients for recipient collection request
type: object
required:
- customerName
- phoneNumber
- timezone
properties:
customerName:
type: string
description: Name of customer
example: Jane Smith
phoneNumber:
type: string
description: Phone Number for the customer
example: (415) 555-1234
timezone:
type: string
description: Timezone the customer is located in. Supported timezones are those found in the IANA
timezone database.
example: America/Los_Angeles
examples:
Email Recipient Collection:
summary: Create recipient collection with email recipients
value:
name: Email collection
startAfter: '2024-05-13T16:32:00.000Z'
recipients:
- customerName: John Baker
emailAddress: john.baker@example.com
timezone: America/Los_Angeles
- customerName: Jane Smith
emailAddress: jane.smith@example.com
timezone: America/New_York
SMS Recipient Collection:
summary: Create recipient collection with sms recipients
value:
name: SMS collection
startAfter: '2024-05-13T16:32:00.000Z'
recipients:
- customerName: John Baker
phoneNumber: '+14155551234'
timezone: America/Los_Angeles
- customerName: Jane Smith
phoneNumber: (212) 555-9876
timezone: America/New_York
Voice Recipient Collection:
summary: Create recipient collection with voice recipients
value:
name: Voice collection
startAfter: '2024-05-13T16:32:00.000Z'
recipients:
- customerName: John Baker
phoneNumber: '+14155551234'
timezone: America/Los_Angeles
- customerName: Jane Smith
phoneNumber: (212) 555-9876
timezone: America/New_York
responses:
'200':
description: created recipient collection
content:
application/json:
schema:
title: Recipient Collection
description: Recipient Collection
type: object
required:
- id
- campaignId
- type
- startAfter
- name
- status
properties:
id:
type: string
description: Unique recipient collection id
example: oiaFOojmQu2v8CRQaVUIjw
campaignId:
type: string
description: Campaign id the recipient collection belongs to
example: qmkz789yRyO6BdC8WeEitA
type:
type: string
description: Type of recipient collection
example: EMAIL
enum:
- EMAIL
- SMS
- VOICE
startAfter:
type: string
format: RFC3339
description: The time after which the recipient collection should start processing
example: '2019-02-21T07:15:19.07272933Z'
endBefore:
type: string
format: RFC3339
description: The time before which the recipient collection should stop processing
example: '2019-02-21T07:15:19.07272933Z'
name:
type: string
description: Name of the recipient collection
example: My Collection
status:
type: string
description: Status of the recipient collection
example: ACTIVE
enum:
- ACTIVE
- CANCELED
- COMPLETED
- PENDING
- SCHEDULED
'404':
description: campaign not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrors'
/api/v1/reports:
post:
tags:
- Reports
summary: Generate a Report
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://connect.gladly.com/docs/help-documentation/reports-and-insights/) section of
the help docs.
requestBody:
description: Parameters describing the report to generate.
content:
application/json:
schema:
title: Report request body
type: object
required:
- metricSet
- startAt
- endAt
properties:
metricSet:
type: string
description: 'This parameter is used to specify that the report should include a predetermined set of metrics.
These are the same reports that you can normally access via UI.
For more information about each report, check out the [Work With OOTB Reports](https://help.gladly.com/docs/export-reports)
section of the help docs.
'
example: ContactSummaryReport
enum:
- AgentAwayTimeReport
- AgentAvailableTimeReportV2
- AgentDurationsReport
- AgentDurationsReportV2
- AgentLoginTimeReport
- AgentSummary
- AgentSummaryV2
- AgentSummaryGlanceReport
- AgentSummaryGlanceReportV2
- AgentTimestampsReport
- FirstContactResolutionByAgentV2Report
- PaymentsByAgentReport
- WorkSessionEventsReportV3
- WorkSessionEventsReportV4
- WorkSessionsReport
- WorkSessionsReportV3
- AnswerUsageReport
- AnswerUsageByAgentReport
- ChannelMixReportV2
- ChannelWaitTimeReport
- ChannelWaitTimeReportV2
- ContactExportReportV3
- ContactSummaryReport
- ContactSummaryReportV2
- ContactSummaryCountsReport
- ContactSummaryDurationsReport
- ContactSummaryDurationsReportV2
- ContactTimestampsReport
- ConversationExportReport
- ConversationSidekickExportReport
- ConversationSummaryReport
- ConversationTimestampsReport
- AbandonedCallsInIVRReport
- AutoThrottleMissedConversationsReport
- IVRExecutiveSummaryReportV2
- IvrEndStatesReportV2
- PaymentsSummaryReport
- ProactiveVoiceSummaryReport
- TopicHierarchyReport
- TaskExportReport
- TaskSummaryReport
- TaskTimestampsReport
- TopicSummaryReport
- AutoThrottleChangesReport
- ChatDisplayPctChangesReport
- HelpCenterAnswerSearchReport
- HelpCenterAnswerUsageReport
- QuickActionsUsageReport
- SelfServiceThreadsReport
- SidekickAssistsByClassificationTopicReport
- GladAppAnswerSearchReport
- GladAppAnswerUsageReport
- GladAppContactPointsReport
- GladlyAISessionsDetailReport
- GladlyAISessionsDetailWithMessagesReport
timezone:
type: string
description: 'The timezone to be used for the report. Supported timezones are those found in the IANA timezone
database.
If omitted, the organization''s default timezone will be used.
'
example: America/Denver
startAt:
type: string
description: 'Starting date at the timezone indicated by the timezone parameter. The report will begin at
midnight of the specified date.
The date should be in the format `YYYY-mm-dd`. For example `2019-05-01`.
'
example: '2019-05-01'
endAt:
type: string
description: 'Ending date at the timezone indicated by the timezone parameter. The report will end just
before midnight of the following day such that the report includes all data for the `endAt` day.
The date should be in the format `YYYY-mm-dd`. For example `2019-05-01`.
'
example: '2019-05-16'
startAtTime:
type: string
description: 'Starting time of the report interval, in ISO 8601 format `YYYY-mm-ddThh:mmZ`. For example
`2020-04-13T19:27Z`.
This filter is optional and only applies to the following `metricSet`s: `AgentSummaryReport` and `ContactExportReportV3`.
If `startAtTime` is supplied, `endAtTime` must also be supplied, and `startAt`, `endAt`, and `timezone`
must not be specified.
'
example: 2020-04-13T19:27Z
endAtTime:
type: string
description: 'Ending time of the report interval, in ISO 8601 format `YYYY-mm-ddThh:mmZ`. For example `2020-04-13T19:27Z`.
This filter is optional and only applies to the following `metricSet`s: `AgentSummaryReport` and `ContactExportReportV3`.
If `endAtTime` is supplied, `startAtTime` must also be supplied, and `startAt`, `endAt`, and `timezone`
must not be specified.
'
example: 2020-04-14T19:27Z
aggregationLevel:
type: string
default: daily
description: '\
The aggregation level for the report.
Applies to the following `metricSet`s: `AgentAwayTimeReport`, `AgentAvailableTimeReportV2`, `AgentLoginTimeReport`,
`AgentSummary`, `AgentSummaryV2`, `AgentSummaryGlanceReport`, `AgentSummaryGlanceReportV2`, `FirstContactResolutionByAgentV2Report`,
`AnswerUsageReport`, `AnswerUsageByAgentReport`, `ChannelMixReportV2`, `ChannelWaitTimeReport`, `ChannelWaitTimeReportV2`,
`ContactSummaryReport`, `ContactSummaryReportV2`, `ContactSummaryCountsReport`, `ContactSummaryDurationsReport`,
`ContactSummaryDurationsReportV2`, `ConversationSummaryReport`, `AbandonedCallsInIVRReport`, `AutoThrottleMissedConversationsReport`,
`PaymentsSummaryReport`, `ProactiveVoiceSummaryReport`, `TopicHierarchyReport`, `TaskSummaryReport`, `HelpCenterAnswerUsageReport`,
`QuickActionsUsageReport`, and `GladAppAnswerUsageReport`.
Note that an individual aggregationLevel may only be available depending on the `metricSet` and date range
selected (e.g.: "halfHourly" is not available on the `AgentSummary` `metricSet` if requesting over 1 month''s
worth of data)
'
enum:
- halfHourly
- daily
- weekly
- monthly
- quarterly
example: daily
filters:
type: object
description: Additional filters that can be applied to the report. Each filter applies to select `metricSet`s.
Compatibility is detailed in the description of each parameter.
properties:
channel:
type: string
default: allChannels
description: '\
Specifies a channel to filter the report by. Specifying a channel filter may alter which metrics are
returned. For details, see the Data Dictionary.
Applies to the following `metricSet`s: `FirstContactResolutionByAgentV2Report`, `WorkSessionsReport`,
`WorkSessionsReportV3`, `ChannelMixReportV2`, `ContactExportReportV3`, `ContactSummaryReport`, `ContactSummaryReportV2`,
`ContactSummaryCountsReport`, `ContactSummaryDurationsReport`, `ContactSummaryDurationsReportV2`,
`TopicHierarchyReport`, `TopicSummaryReport`.
'
enum:
- allChannels
- chat
- email
- fbMessenger
- sms
- twitter
- voice
- whatsapp
- instagramDirect
example: voice
inboxes:
type: array
items:
type: string
default: []
description: '\
An array containing inbox IDs of the inboxes for which to filter this report.
Passing an inbox ID for a nonexistent inbox will result in an error response.
Applies to the following `metricSet`s: `FirstContactResolutionByAgentV2Report`, `WorkSessionsReport`,
`WorkSessionsReportV3`, `ChannelMixReportV2`, `ChannelWaitTimeReport`,`ChannelWaitTimeReportV2`, `ContactExportReportV3`,
`ContactSummaryReport`,`ContactSummaryReportV2`, `ContactSummaryCountsReport`, `ContactSummaryDurationsReport`,
`ContactSummaryDurationsReportV2`, `ConversationExportReport`, `ConversationSidekickExportReport`,
`ConversationSummaryReport`, `TopicHierarchyReport`, `TopicSummaryReport`, `TaskExportReport`, and
`TaskSummaryReport`.
See the [Inboxes API](#operation/getInboxes) documentation for more details on how to get inbox IDs.
'
example:
- c23d738960f946988e943f400313133a
- 2c475a4351ce4aa39ff5cb9f526d77db
teams:
type: array
items:
type: string
default: []
description: '\
An array containing team IDs of the teams to be included in the report.
Passing a team ID for a nonexistent team will result in an error response.
Applies to the following `metricSet`s: `AgentAvailableTimeReportV2`, `AgentDurationsReport`, `AgentDurationsReportV2`,
`AgentLoginTimeReport`, `AgentSummary`, `AgentSummaryV2`, `AgentSummaryGlanceReport`, `AgentSummaryGlanceReportV2`,
`AgentTimestampsReport`, `FirstContactResolutionByAgentV2Report`, `WorkSessionsReport`, `WorkSessionsReportV3`,
`AnswerUsageByAgentReport`, `TaskExportReport`, and `TaskSummaryReport`.
See the [Teams API](#operation/getTeams) documentation for more details on how to get team IDs.
'
example:
- dd96426e5d2b4fed86dad91cdcc84112
- cab03fe3066e4fa7ba3397e8925c5132
phoneNumber:
type: string
description: 'Specifies which inbound phone number the report is to be generated for.
The number must be in E164 format. For example `+15555555555`.
Applies to and is **required** for the following `metricSet`s: `IVRExecutiveSummaryReportV2`, and
`IvrEndStatesReportV2`.
'
example: '+15555555555'
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:
description: CSV report
format: binary
'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
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](#section/Ping-Event).
You are limited to 20 webhooks for your organization.
'
operationId: createWebhook
requestBody:
required: true
description: Webhook to add
content:
application/json:
schema:
title: Webhook
allOf:
- $ref: '#/paths/~1api~1v1~1webhooks~1%7BwebhookId%7D/patch/requestBody/content/application~1json/schema'
- type: object
required:
- url
- events
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'
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
responses:
'201':
description: Created webhook
headers:
Location:
schema:
type: string
example: /api/v1/webhooks/c5yeqK8VTlm9xAXgvq_5-w
description: Location of the created webhook
'400':
description: Invalid field(s) in request body
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
get:
tags:
- Webhooks
summary: List Webhooks
description: 'Returns a list of webhooks.
'
operationId: getWebhooks
responses:
'200':
description: Webhook
content:
application/json:
schema:
title: Webhooks
type: array
items:
$ref: '#/paths/~1api~1v1~1webhooks~1%7BwebhookId%7D/patch/requestBody/content/application~1json/schema'
/api/v1/webhooks/{webhookId}:
parameters:
- name: webhookId
in: path
description: id of the webhook
required: true
schema:
type: string
example: a9dIl-kKRrKUZLQtJ-tjtw
patch:
tags:
- Webhooks
summary: Update Webhook
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](#section/Ping-Event).
'
operationId: updateWebhook
requestBody:
required: true
description: JSON patch of webhook properties to insert or update
content:
application/json:
schema:
title: Webhook
allOf:
- title: Webhook
properties:
id:
type: string
readOnly: true
description: id of the webhook
example: a9dIl-kKRrKUZLQtJ-tjtw
name:
type: string
maxLength: 200
description: friendly name of the webhook
example: CSAT integration
events:
type: array
description: list of events that trigger the webhook. More events are coming soon. Please see [Events](#operation/Events)
for more information about the data included for each event type.
example:
- CONVERSATION/CLOSED
items:
type: string
enum:
- AGENT_AVAILABILITY/FOCUS_ENTERED
- AGENT_AVAILABILITY/FOCUS_EXITED
- AGENT_AVAILABILITY/UPDATED
- AGENT_STATUS/CHANGED_ACTIVE_REASON
- AGENT_STATUS/LOGGED_IN
- AGENT_STATUS/LOGGED_OUT
- AGENT_STATUS/RETURNED_FROM_AWAY
- AGENT_STATUS/WENT_AWAY
- CONTACT/ENDED
- CONTACT/FULFILLED
- CONTACT/HOLD_ENDED
- CONTACT/HOLD_STARTED
- CONTACT/JOINED
- CONTACT/MESSAGE_RECEIVED
- CONTACT/MESSAGE_SENT
- CONTACT/OFFER_ACCEPTED
- CONTACT/OFFERED
- CONTACT/OFFER_REJECTED
- CONTACT/STARTED
- CONTACT/TRANSFERRED
- CONVERSATION/CLOSED
- CONVERSATION/CREATED
- CONVERSATION/CUSTOM_ATTRIBUTE_ADDED
- CONVERSATION/CUSTOM_ATTRIBUTE_REMOVED
- CONVERSATION/NOTE_CREATED
- CONVERSATION/REOPENED
- CONVERSATION/TOPIC_ADDED
- CONVERSATION/TOPIC_REMOVED
- CONVERSATION_ASSIGNEE/UPDATED
- CONVERSATION_STATUS/UPDATED
- CUSTOMER/MERGED
- CUSTOMER_PROFILE/CREATED
- CUSTOMER_PROFILE/DELETED
- CUSTOMER_PROFILE/MERGED (deprecated)
- CUSTOMER_PROFILE/UPDATED
- EXPORT_JOB/COMPLETED
- EXPORT_JOB/FAILED
- PAYMENT_REQUEST/CREATED
- PAYMENT_REQUEST/STATUS_CHANGED
- PAYMENT_REQUEST/VIEWED
- TASK/ASSIGNEE_UPDATED
- TASK/CLOSED
- TASK/COMMENT_ADDED
- TASK/CONTENT_UPDATED
- TASK/CREATED
- TASK/DUE_DATE_UPDATED
- TASK/FOLLOWER_ADDED
- TASK/FOLLOWER_REMOVED
- TASK/REOPENED
url:
type: string
description: your URL that POST requests are sent to when events occur. HTTPS is required and this value
must be unique across all webhooks.
example: https://gateway.organization.com/gladly/webhook
credentials:
title: Basic Auth Credentials
writeOnly: true
required:
- username
- password
properties:
username:
type: string
description: basic auth username
example: integrations@organization.com
password:
type: string
description: basic auth password
example: ''
realm:
type: string
description: optional realm to authenticate with
example: ''
headers:
title: HTTP Headers
type: object
description: custom HTTP headers to include in every request
writeOnly: true
additionalProperties:
type: string
description: static value for the HTTP header
example:
X-API-key:
X-Gladly-token:
createdAt:
type: string
format: RFC3339
readOnly: true
description: time the webhook was created
example: '2019-07-03T04:30:12.07Z'
updatedAt:
type: string
format: RFC3339
readOnly: true
description: time the item was last updated
example: '2019-07-09T09:00:10.00Z'
hasCredentials:
type: boolean
readOnly: true
description: whether the webhook has been configured with basic auth credentials
example: true
headerKeys:
type: array
readOnly: true
description: list of header keys (without values) to include in every request to your URL.
example:
- X-Gladly-Key
items:
type: string
- type: object
properties:
enabled:
type: boolean
default: false
description: whether the webhook is delivering notifications
example: false
disabledAtDueToRetryLimit:
type: string
format: RFC3339
readOnly: true
description: time the webhook was disabled due to our retry limit
example: '2019-07-10T12:00:00.00Z'
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
description: 'Delete a webhook by ID
'
operationId: deleteWebhook
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
description: 'Get a webhook by ID
'
operationId: getWebhook
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:
- url: https://gateway.organization.com
description: Web service hosted on your servers should be reachable from the Gladly cluster
post:
tags:
- Payloads
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.
'
operationId: Events
requestBody:
description: the event payload
content:
application/json:
schema:
title: Event
description: data about the event
oneOf:
- title: Agent Availability Updated
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: zGaHXjD4SR-moMR9LbULDa
type:
type: string
example: AGENT_AVAILABILITY/UPDATED
enum:
- AGENT_AVAILABILITY/UPDATED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
title: Initiator
description: Type and ID (if applicable) of the entity that triggered the event.
required:
- id
- type
properties:
id:
type: string
description: ID of the entity that triggered the event.
example: NFpDZtfqhk2pI6fjaVDlFf
type:
type: string
description: The type of the entity that triggered the event.
example: AGENT
content:
title: Content
description: Content for event
required:
- agentId
- availableFor
- occurredAt
properties:
agentId:
type: string
description: ID of the agent whose availability was updated.
example: zGaHXjD4SR-moMR9LbULDa
availableFor:
type: array
enum:
- MAIL
- MESSAGING
- TASK
- VOICE
description: 'The set of channel types for which the agent is available after changing their availability.
'
example:
- MAIL
- VOICE
occurredAt:
type: string
format: ISO 8601
description: Timestamp when the action occurred
example: '2019-07-03T04:30:12.07Z'
- title: Agent Changed Active Reason
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: AGENT_STATUS/CHANGED_ACTIVE_REASON
enum:
- AGENT_STATUS/CHANGED_ACTIVE_REASON
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- agentId
- occurredAt
properties:
agentId:
type: string
description: ID of the agent who changed active reason
example: zGaHXjD4SR-moMR9LbULDa
occurredAt:
type: string
format: ISO 8601
description: Timestamp when the action occurred
example: '2019-07-03T04:30:12.07Z'
activeReason:
title: Active Reason
description: Working states used by Agents to indicate what they are currently doing. The system sets
a configurable default value upon login or return from away. The agent can subsequently update their
active status.
required:
- id
properties:
id:
type: string
description: ID of the active reason
example: eRaHXjD4li-moMR8LbULXc
name:
type: string
description: Name of the active reason
example: Triaging Customer
- title: Agent Logged In
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: zGaHXjD4SR-moMR9LbULDa
type:
type: string
example: AGENT_STATUS/LOGGED_IN
enum:
- AGENT_STATUS/LOGGED_IN
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- agentId
- occurredAt
properties:
agentId:
type: string
description: ID of the agent who logged in.
example: zGaHXjD4SR-moMR9LbULDa
occurredAt:
type: string
format: ISO 8601
description: Timestamp when the action occurred
example: '2019-07-03T04:30:12.07Z'
activeReason:
title: Active Reason
description: Working states used by Agents to indicate what they are currently doing. The system sets
a configurable default value upon login or return from away. The agent can subsequently update their
active status.
required:
- id
properties:
id:
type: string
description: ID of the active reason
example: bHaHXjD4li-moMR8LbULZc
name:
type: string
description: Name of the active reason
example: Triaging Inbox (Default)
- title: Agent Logged Out
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: zGaHXjD4SR-moMR9LbULDa
type:
type: string
example: AGENT_STATUS/LOGGED_OUT
enum:
- AGENT_STATUS/LOGGED_OUT
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- agentId
- occurredAt
properties:
agentId:
type: string
description: ID of the agent who logged out.
example: zGaHXjD4SR-moMR9LbULDa
occurredAt:
type: string
format: ISO 8601
description: Timestamp when the action occurred
example: '2019-07-03T04:30:12.07Z'
- title: Agent Returned From Away
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: zGaHXjD4SR-moMR9LbULDa
type:
type: string
example: AGENT_STATUS/RETURNED_FROM_AWAY
enum:
- AGENT_STATUS/RETURNED_FROM_AWAY
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- agentId
- awayAt
- occurredAt
properties:
agentId:
type: string
description: ID of the agent who returned from away.
example: zGaHXjD4SR-moMR9LbULDa
awayAt:
type: string
format: ISO 8601
description: Timestamp when the agent previously went away
example: '2019-07-03T04:30:12.07Z'
activeReason:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/2/properties/content/properties/activeReason'
awayReason:
title: Away Reason
description: The reason the Agent went away. Reason will not be provided if Agent is auto-Away after
the configured idle period. Agents can also be auto-logged out after an idle period, in which case
that Away period will not have a corresponding AGENT_STATUS/RETURNED_FROM_AWAY event.
required:
- id
properties:
id:
type: string
description: ID of the away reason
example: aGaHXjD4li-moMR8LbULZb
name:
type: string
description: name of the away reason
example: coffee break
occurredAt:
type: string
format: ISO 8601
description: Timestamp when the action occurred
example: '2019-07-03T04:30:12.07Z'
- title: Agent Went Away
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: zGaHXjD4SR-moMR9LbULDa
type:
type: string
example: AGENT_STATUS/WENT_AWAY
enum:
- AGENT_STATUS/WENT_AWAY
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- agentId
- occurredAt
properties:
agentId:
type: string
description: ID of the agent who went away.
example: zGaHXjD4SR-moMR9LbULDa
awayReason:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/4/properties/content/properties/awayReason'
occurredAt:
type: string
format: ISO 8601
description: Timestamp when the action occurred
example: '2019-07-03T04:30:12.07Z'
- title: Contact Ended
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: CONTACT/ENDED
enum:
- CONTACT/ENDED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- channel
- contactId
- conversationId
- customerId
- status
- context
properties:
channel:
type: string
description: The channel of the contact.
enum:
- CHAT
- EMAIL
- FB_MESSENGER
- INSTAGRAM_DIRECT
- PHONE_CALL
- SMS
- VOICEMAIL
- WHATSAPP
example: SMS
contactId:
type: string
description: The ID of the contact.
example: dzweSumI4bFxjlT8LApOVV
conversationId:
type: string
description: The ID of the conversation to which the contact is associated.
example: K98jhf874HjDFkA1457K86
customerId:
type: string
description: The ID of the customer profile to which the contact is associated.
example: gHufx-U3QqOmhvFuViceTw
reason:
type: string
enum:
- AGENT_ENDED
- CONVERSATION_CLOSED
- CUSTOMER_ABANDONED
- CUSTOMER_DELETED
- CUSTOMER_NO_REPLY
- MERGED
- NO_REPLY_NEEDED
- STARTED_NEW
description: The reason why the contact was ended.
example: MERGED
status:
type: string
enum:
- ABANDONED
- ANSWERED
- UNANSWERED
- UNKNOWN
description: The status of the contact.
example: ANSWERED
context:
title: Contact Context
description: The state of the contact immediately before the event occurred.
required:
- assignee
properties:
assignee:
title: Assignee
description: Inbox and agent assignee of the contact just before the event was triggered.
required:
- inboxId
properties:
inboxId:
type: string
description: ID of the inbox the contact was assigned to just before the event was triggered.
You can look up the id in the Gladly UI.
example: NFpDZtfqhk2pI6fjaVDlFf
agentId:
type: string
description: ID of the agent the contact was assigned to just before the event was triggered.
You can look up the id in the Gladly UI.
example: zGaHXjD4SR-moMR9LbULDa
- title: Contact Fulfilled
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: CONTACT/FULFILLED
enum:
- CONTACT/FULFILLED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- channel
- contactId
- conversationId
- customerId
- fulfilledType
- context
properties:
channel:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/channel'
contactId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/contactId'
conversationId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/conversationId'
customerId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/customerId'
fulfilledType:
type: string
enum:
- CANCELED
- RESPONDED
description: The type of fulfillment.
example: CANCELED
context:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/context'
- title: Contact Hold Ended
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: CONTACT/HOLD_ENDED
enum:
- CONTACT/HOLD_ENDED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- channel
- contactId
- conversationId
- customerId
- reason
- context
properties:
channel:
type: string
description: The only channel for contact holds is PHONE_CALL.
enum:
- PHONE_CALL
example: PHONE_CALL
contactId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/contactId'
conversationId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/conversationId'
customerId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/customerId'
description: The ID of the contact.
example: dzweSumI4bFxjlT8LApOVV
reason:
type: string
enum:
- COLD_TRANSFER
- CONFERENCE
- MANUAL
- WARM_TRANSFER
description: The reason the phone call contact was put on hold
example: CONFERENCE
context:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/context'
- title: Contact Hold Started
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: CONTACT/HOLD_STARTED
enum:
- CONTACT/HOLD_STARTED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- channel
- contactId
- conversationId
- customerId
- reason
- context
properties:
channel:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/8/properties/content/properties/channel'
contactId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/contactId'
conversationId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/conversationId'
customerId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/customerId'
reason:
type: string
enum:
- COLD_TRANSFER
- CONFERENCE
- MANUAL
- WARM_TRANSFER
description: The reason the phone call contact was put on hold
example: CONFERENCE
context:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/context'
- title: Contact Joined
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: CONTACT/JOINED
enum:
- CONTACT/JOINED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- channel
- contactId
- conversationId
- customerId
- messageId
- context
properties:
channel:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/channel'
contactId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/contactId'
conversationId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/conversationId'
customerId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/customerId'
context:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/context'
- title: Contact Message Received
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: CONTACT/MESSAGE_RECEIVED
enum:
- CONTACT/MESSAGE_RECEIVED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- channel
- contactId
- conversationId
- customerId
- messageId
- context
properties:
channel:
type: string
description: The channel of the contact.
enum:
- CHAT
- EMAIL
- FB_MESSENGER
- INSTAGRAM_DIRECT
- SMS
- VOICEMAIL
- WHATSAPP
example: SMS
contactId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/contactId'
conversationId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/conversationId'
customerId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/customerId'
messageId:
type: string
description: The ID of the message that was received. This message can be retreived using the Gladly
Conversations API (`/api/v1/conversation-items/{itemId}`)
example: dzweSumI4bFxjlT8LApOVV
context:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/context'
- title: Contact Message Sent
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: CONTACT/MESSAGE_SENT
enum:
- CONTACT/MESSAGE_SENT
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- channel
- contactId
- conversationId
- customerId
- messageId
- context
properties:
channel:
type: string
description: The channel of the contact.
enum:
- CHAT
- EMAIL
- FB_MESSENGER
- INSTAGRAM_DIRECT
- SMS
- WHATSAPP
example: SMS
contactId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/contactId'
conversationId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/conversationId'
customerId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/customerId'
messageId:
type: string
description: The ID of the message that was sent
example: dzweSumI4bFxjlT8LApOVV
context:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/context'
- title: Contact Offer Accepted
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: CONTACT/OFFER_ACCEPTED
enum:
- CONTACT/OFFER_ACCEPTED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- channel
- contactId
- conversationId
- customerId
- agentId
- context
properties:
channel:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/channel'
contactId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/contactId'
conversationId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/conversationId'
customerId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/customerId'
agentId:
type: string
description: The ID of the assigned agent after the offer was accepted.
example: dzweSumI4bFxjlT8LApOVV
context:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/context'
- title: Contact Offer Rejected
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: CONTACT/OFFER_REJECTED
enum:
- CONTACT/OFFER_REJECTED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- channel
- contactId
- conversationId
- customerId
- agentId
- reason
- context
properties:
channel:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/channel'
contactId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/contactId'
conversationId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/conversationId'
customerId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/customerId'
agentId:
type: string
description: The ID of the agent who was offered the contact.
example: dzweSumI4bFxjlT8LApOVV
reason:
enum:
- DECLINED
- MISSED
- DEVICE ERROR
description: The reason the offer was rejected by the system or by an agent.
context:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/context'
- title: Contact Offered
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: CONTACT/OFFERED
enum:
- CONTACT/OFFERED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- channel
- contactId
- conversationId
- customerId
- agentId
- context
properties:
channel:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/channel'
contactId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/contactId'
conversationId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/conversationId'
customerId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/customerId'
agentId:
type: string
description: The ID of the agent being offered the contact.
example: dzweSumI4bFxjlT8LApOVV
matchReasons:
type: array
description: 'The names of the People Match Priority Boosts that boosted the score for the contact
offer.
'
example:
- Transfer
- Receipt Request
context:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/context'
- title: Contact Started
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: CONTACT/STARTED
enum:
- CONTACT/STARTED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- channel
- contactId
- conversationId
- customerId
- context
properties:
channel:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/channel'
contactId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/contactId'
conversationId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/conversationId'
customerId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/customerId'
dueAt:
format: ISO 8601
description: The due date of the contact
example: '2019-07-03T04:30:12.07Z'
entryPoint:
type: string
description: The “To” address (e.g. phone number, email address) that the customer reached out to
example: endpoint-1
finalIVRSelection:
type: string
description: Final selection made in the IVR before the contact is queued
example: __billing
context:
description: The state of the contact immediately before the event occurred.
required:
- assignee
properties:
assignee:
description: Inbox and agent assignee of the contact when the event was triggered.
required:
- inboxId
properties:
inboxId:
type: string
description: ID of the inbox the contact was assigned to when the event was triggered. You
can look up the id in the Gladly UI.
example: NFpDZtfqhk2pI6fjaVDlFf
agentId:
type: string
description: ID of the agent the contact was assigned to when the event was triggered. You
can look up the id in the Gladly UI.
example: zGaHXjD4SR-moMR9LbULDa
- title: Contact Transferred
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: CONTACT/TRANSFERRED
enum:
- CONTACT/TRANSFERRED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- channel
- contactId
- conversationId
- customerId
- reason
- transferType
- assignee
- context
properties:
channel:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/channel'
contactId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/contactId'
conversationId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/conversationId'
customerId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/customerId'
transferType:
type: string
enum:
- COLD
- WARM
description: The type of transfer.
example: COLD
reason:
enum:
- AUTOMATION
- MANUAL
- MERGE
- UNKNOWN
description: The reason the contact was transferred
example: MANUAL
assignee:
type: object
description: The new assignee after the contact was transferred
required:
- inboxId
properties:
inboxId:
type: string
description: ID of the inbox the contact was assigned to after the event occurred. You can look
up the id in the Gladly UI.
example: NFpDZtfqhk2pI6fjaVDlFf
agentId:
type: string
description: ID of the agent the contact was assigned to after the event occurred. You can look
up the id in the Gladly UI.
example: zGaHXjD4SR-moMR9LbULDa
context:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/context'
- title: Conversation Assignee Updated
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: CONVERSATION_ASSIGNEE/UPDATED
enum:
- CONVERSATION_ASSIGNEE/UPDATED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for the event
required:
- customerId
- conversationId
- reason
- assignee
- context
properties:
customerId:
type: string
description: The ID of the customer profile to which the conversation is associated.
example: THx8Z8y-ScuMoqBH8Awtng
conversationId:
type: string
description: The ID of the conversation.
example: aGaHXjD4li-moMR8LbULZb
reason:
type: string
description: The reason for the assignee update
enum:
- AUTOMATED_ASSIGNMENT
- CONTACT_DECLINED
- CONTACT_INBOUND
- CONTACT_MISSED
- CONTACT_OFFERED
- CUSTOMER_CONVERSATION_MERGE
- DEDICATED_HERO_ASSIGN
- DEDICATED_HERO_CHANGE
- DEVICE_ERROR
- MANUAL
- MESSAGE_OUTBOUND
- CONTACT_OFFER_CONFLICT
- PHONE_CALL_TRANSFER
- QUEUE_IVR_TRANSFER
- REROUTED_UNASSIGN
- USER_DEACTIVATION
assignee:
title: Assignee
description: Inbox and agent assignee being assigned the conversation.
required:
- inboxId
properties:
inboxId:
type: string
description: ID of the inbox the conversation is being assigned. You can look up the id in the
Gladly UI.
example: NFpDZtfqhk2pI6fjaVDlFf
agentId:
type: string
description: ID of the agent the conversation is being assigned. You can look up the id in the
Gladly UI.
example: zGaHXjD4SR-moMR9LbULDa
context:
title: Conversation Context
description: The state of the conversation immediately before the event occurred.
required:
- assignee
properties:
assignee:
description: Inbox and agent assignee of the conversation when the event was triggered.
required:
- inboxId
properties:
inboxId:
type: string
description: ID of the inbox the conversation was assigned to when the event was triggered.
You can look up the id in the Gladly UI.
example: NFpDZtfqhk2pI6fjaVDlFf
agentId:
type: string
description: ID of the agent the conversation was assigned to when the event was triggered.
You can look up the id in the Gladly UI.
example: zGaHXjD4SR-moMR9LbULDa
- title: Conversation Closed
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: CONVERSATION/CLOSED
enum:
- CONVERSATION/CLOSED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Conversation
description: ''
required:
- customerId
- conversationId
- context
properties:
customerId:
type: string
description: The ID of the customer profile to which the conversation is associated.
example: THx8Z8y-ScuMoqBH8Awtng
conversationId:
type: string
description: The ID of the conversation.
example: aGaHXjD4li-moMR8LbULZb
context:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/18/properties/content/properties/context'
- title: Conversation Created
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: CONVERSATION/CREATED
enum:
- CONVERSATION/CREATED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/19/properties/content'
- title: Conversation Custom Attribute Added
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: CONVERSATION/CUSTOM_ATTRIBUTE_ADDED
enum:
- CONVERSATION/CUSTOM_ATTRIBUTE_ADDED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: ConversationCustomAttribute
description: Content for the event
required:
- customerId
- conversationId
- customAttributeId
- customAttributeKey
- customAttributeValue
properties:
customerId:
type: string
description: The ID of the customer profile to which the conversation is associated.
example: THx8Z8y-ScuMoqBH8Awtng
conversationId:
type: string
description: The ID of the conversation.
example: aGaHXjD4li-moMR8LbULZb
customAttributeId:
type: string
description: The ID of the custom attribute.
example: aGaHXjD4li-moMR8LbULZb
customAttributeKey:
type: string
description: The Key of the custom attribute.
example: orderId
customAttributeValue:
type: string
description: The Value of the custom attribute.
example: '1232424890'
- title: Conversation Custom Attribute Removed
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: CONVERSATION/CUSTOM_ATTRIBUTE_REMOVED
enum:
- CONVERSATION/CUSTOM_ATTRIBUTE_REMOVED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/21/properties/content'
- title: Conversation Note Created
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: CONVERSATION/NOTE_CREATED
enum:
- CONVERSATION/NOTE_CREATED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for the event
required:
- noteId
- customerId
- conversationId
properties:
noteId:
type: string
description: The ID of the note being created
example: UAAAlBdOQwGl7mzqQUfVow
customerId:
type: string
description: The ID of the customer profile to which the conversation is associated.
example: THx8Z8y-ScuMoqBH8Awtng
conversationId:
type: string
description: The ID of the conversation.
example: aGaHXjD4li-moMR8LbULZb
- title: Conversation Reopened
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: CONVERSATION/REOPENED
enum:
- CONVERSATION/REOPENED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/19/properties/content'
- title: Conversation Status Updated
type: object
required:
- id
- type
- timestamp
- content
properties:
id:
type: string
description: Unique event ID
example: zGaHXjD4SR-moMR9LbULDa
type:
type: string
example: CONVERSATION_STATUS/UPDATED
enum:
- CONVERSATION_STATUS/UPDATED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
content:
title: CONVERSATION_STATUS/UPDATED
properties:
conversationId:
type: string
description: id of the conversation for which the status was updated
example: IBBcbj2ARXWwvUGV_LbfEQ
customerId:
type: string
description: id of the customer whose conversation's status was updated
example: qJaE0di0SdOWNnq5dT13Aw
- title: Conversation Topic Added
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: CONVERSATION/TOPIC_ADDED
enum:
- CONVERSATION/TOPIC_ADDED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for the event
required:
- customerId
- conversationId
- topicId
- context
properties:
customerId:
type: string
description: The ID of the customer profile to which the conversation is associated.
example: THx8Z8y-ScuMoqBH8Awtng
conversationId:
type: string
description: The ID of the conversation.
example: aGaHXjD4li-moMR8LbULZb
topicId:
type: string
description: The ID of the topic being added to the conversation.
example: 0f2oNq7sR6CJpKq0WDbTbg
context:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/18/properties/content/properties/context'
- title: Conversation Topic Removed
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: CONVERSATION/TOPIC_REMOVED
enum:
- CONVERSATION/TOPIC_REMOVED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for the event
required:
- customerId
- conversationId
- topicId
- context
properties:
customerId:
type: string
description: The ID of the customer profile to which the conversation is associated.
example: THx8Z8y-ScuMoqBH8Awtng
conversationId:
type: string
description: The ID of the conversation.
example: aGaHXjD4li-moMR8LbULZb
topicId:
type: string
description: The ID of the topic removed from the conversation.
example: 0f2oNq7sR6CJpKq0WDbTbg
context:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/18/properties/content/properties/context'
- title: Customer Merged
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: CUSTOMER/MERGED
enum:
- CUSTOMER/MERGED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for the event
required:
- destinationCustomerId
- destinationConversationId
- sourceCustomerId
- sourceConversationId
properties:
destinationCustomerId:
type: string
description: The ID of the combined customer profile that remains after the merge.
example: THx8Z8y-ScuMoqBH8Awtng
destinationConversationId:
type: string
description: The ID of the combined open conversation (if applicable) that remains after the merge.
example: aGaHXjD4li-moMR8LbULZb
sourceCustomerId:
type: string
description: The ID of the customer profile that is being merged into another customer profile.
example: 0f2oNq7sR6CJpKq0WDbTbg
sourceConversationId:
type: string
description: The ID of the open conversation (if applicable) that is being merged into another open
conversation.
example: fjsSrGvhv83-k1hjfoz742
- title: Customer Profile Created
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: CUSTOMER_PROFILE/CREATED
enum:
- CUSTOMER_PROFILE/CREATED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Customer Profile Created
description: Content for the event
required:
- customerId
properties:
customerId:
type: string
description: The ID of the customer profile that was created.
example: THx8Z8y-ScuMoqBH8Awtng
- title: Customer Profile Deleted
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: CUSTOMER_PROFILE/DELETED
enum:
- CUSTOMER_PROFILE/DELETED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Customer Profile Deleted
description: Content for the event
required:
- customerId
properties:
customerId:
type: string
description: The ID of the customer profile that was deleted.
example: THx8Z8y-ScuMoqBH8Awtng
- title: Customer Profile Merged (deprecated)
type: object
required:
- id
- type
- timestamp
- content
properties:
id:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/25/properties/id'
type:
type: string
example: CUSTOMER_PROFILE/MERGED
enum:
- CUSTOMER_PROFILE/MERGED
timestamp:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/25/properties/timestamp'
content:
title: CUSTOMER_PROFILE/MERGED (deprecated)
properties:
sourceCustomerId:
type: string
description: id of the customer that was merged
example: qJaE0di0SdOWNnq5dT13Aw
destinationCustomerId:
type: string
description: id of the customer that the source customer was merged into
example: qJaE0di0SdOWNnq5dT13Aw
- title: Customer Profile Updated
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: CUSTOMER_PROFILE/UPDATED
enum:
- CUSTOMER_PROFILE/UPDATED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Customer Profile Updated
description: Content for the event
required:
- customerId
properties:
customerId:
type: string
description: The ID of the customer profile that was updated.
example: THx8Z8y-ScuMoqBH8Awtng
- title: Export Job Completed
type: object
required:
- id
- type
- timestamp
- content
properties:
id:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/25/properties/id'
type:
type: string
example: EXPORT_JOB/COMPLETED
enum:
- EXPORT_JOB/COMPLETED
timestamp:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/25/properties/timestamp'
content:
title: EXPORT_JOB/COMPLETED
properties:
jobId:
type: string
description: id of the export job that has completed
- title: Export Job Failed
type: object
required:
- id
- type
- timestamp
- content
properties:
id:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/25/properties/id'
type:
type: string
example: EXPORT_JOB/FAILED
enum:
- EXPORT_JOB/FAILED
timestamp:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/25/properties/timestamp'
content:
title: EXPORT_JOB/FAILED
properties:
jobId:
type: string
description: id of the export job that has failed
- title: PING
description: a special event that is sent when webhooks are created or updated. See [Ping Event](#section/Ping-Event)
for more information.
- title: Payment Request Created
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: PAYMENT_REQUEST/CREATED
enum:
- PAYMENT_REQUEST/CREATED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Payment Request Created
description: Content for the event
required:
- contactId
- customerId
- conversationId
- paymentRequestId
- context
properties:
contactId:
type: string
description: The ID of the contact to which the payment request is associated.
example: aGaHXjD4li-moMR8LbULZb
customerId:
type: string
description: The ID of the customer profile to which the payment request is associated.
example: THx8Z8y-ScuMoqBH8Awtng
conversationId:
type: string
description: The ID of the conversation to which the payment request is associated.
example: pJpmy-qjazfzJh1K8gc1BR
paymentRequestId:
type: string
description: The ID of the payment request
example: aGaHXjD4li-moMR8LbULZb
context:
title: Context
description: Context for Payment Request
required:
- currency
- monetaryUnit
properties:
currency:
type: string
description: Currency of the payment request
monetaryUnit:
type: number
description: Amount of the payment request
- title: Payment Status Changed
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: PAYMENT_REQUEST/STATUS_CHANGED
enum:
- PAYMENT_REQUEST/STATUS_CHANGED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for Payment Status Changed
required:
- contactId
- conversationId
- customerId
- paymentRequestId
- oldStatus
- newStatus
- context
properties:
contactId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/contactId'
conversationId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/conversationId'
customerId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6/properties/content/properties/customerId'
paymentRequestId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/36/properties/content/properties/paymentRequestId'
oldStatus:
type: string
description: Previous status of the payment request
example: REQUESTING
enum:
- COMPLETED
- DECLINED
- ERROR
- REQUESTING
- SUBMITTED
- TIMED_OUT
newStatus:
type: string
description: New status of the payment request
example: COMPLETED
enum:
- COMPLETED
- DECLINED
- ERROR
- REQUESTING
- SUBMITTED
- TIMED_OUT
context:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/36/properties/content/properties/context'
- title: Payment Request Viewed
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: PAYMENT_REQUEST/VIEWED
enum:
- PAYMENT_REQUEST/VIEWED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Payment Request Viewed
description: Content for the event
required:
- contactId
- customerId
- conversationId
- paymentRequestId
- context
properties:
contactId:
type: string
description: The ID of the contact to which the payment request is associated.
example: aGaHXjD4li-moMR8LbULZb
customerId:
type: string
description: The ID of the customer profile to which the payment request is associated.
example: THx8Z8y-ScuMoqBH8Awtng
conversationId:
type: string
description: The ID of the conversation to which the payment request is associated.
example: aGaHXjD4li-moMR8LbULZb
paymentRequestId:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/36/properties/content/properties/paymentRequestId'
context:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/36/properties/content/properties/context'
- title: Task Assignee Updated
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: TASK/ASSIGNEE_UPDATED
enum:
- TASK/ASSIGNEE_UPDATED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- assignee
- customerId
- taskId
- context
properties:
assignee:
type: object
description: The new assignee for the task.
required:
- inboxId
properties:
inboxId:
type: string
description: ID of the inbox the task is now assigned to. You can look up the id in the Gladly
UI.
example: NFpDZtfqhk2pI6fjaVDlFf
agentId:
type: string
description: ID of the agent the task is now assigned to. You can look up the id in the Gladly
UI.
example: zGaHXjD4SR-moMR9LbULDa
customerId:
type: string
description: The ID of the customer profile to which the task is associated.
example: gHufx-U3QqOmhvFuViceTw
taskId:
type: string
description: The ID of the task.
example: dzweSumI4bFxjlT8LApOVV
context:
title: Task Context
description: The state of the task immediately before the event occurred.
required:
- createdAt
properties:
assignee:
title: Assignee
description: Inbox and agent assignee of the task just before the event was triggered.
required:
- inboxId
properties:
inboxId:
type: string
description: ID of the inbox the task is assigned to. You can look up the id in the Gladly
UI.
example: NFpDZtfqhk2pI6fjaVDlFf
agentId:
type: string
description: ID of the agent the task is assigned to. You can look up the id in the Gladly
UI.
example: zGaHXjD4SR-moMR9LbULDa
dueAt:
description: Time when the task will be due.
type: string
format: RFC3339
example: '2020-03-15T06:13:00.125Z'
createdAt:
type: string
format: RFC3339
description: Timestamp when the action occurred.
example: '2019-07-03T04:30:12.07Z'
- title: Task Closed
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: TASK/CLOSED
enum:
- TASK/CLOSED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- customerId
- taskId
- context
properties:
customerId:
type: string
description: The ID of the customer profile to which the task is associated.
example: gHufx-U3QqOmhvFuViceTw
taskId:
type: string
description: The ID of the task.
example: dzweSumI4bFxjlT8LApOVV
context:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/39/properties/content/properties/context'
- title: Task Comment Added
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: TASK/COMMENT_ADDED
enum:
- TASK/COMMENT_ADDED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- customerId
- taskId
- commentId
- context
properties:
customerId:
type: string
description: The ID of the customer profile to which the task is associated.
example: gHufx-U3QqOmhvFuViceTw
taskId:
type: string
description: The ID of the task.
example: dzweSumI4bFxjlT8LApOVV
commentId:
type: string
description: The ID of the comment that was added to the task.
example: pOVVdzweSumI4bFxjlT8LA
context:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/39/properties/content/properties/context'
- title: Task Content Updated
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: TASK/CONTENT_UPDATED
enum:
- TASK/CONTENT_UPDATED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- customerId
- taskId
- dueAt
- context
properties:
customerId:
type: string
description: The ID of the customer profile to which the task is associated.
example: gHufx-U3QqOmhvFuViceTw
taskId:
type: string
description: The ID of the task.
example: dzweSumI4bFxjlT8LApOVV
context:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/39/properties/content/properties/context'
- title: Task Created
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: TASK/CREATED
enum:
- TASK/CREATED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- customerId
- taskId
- context
properties:
customerId:
type: string
description: The ID of the customer profile to which the task is associated.
example: gHufx-U3QqOmhvFuViceTw
taskId:
type: string
description: The ID of the task.
example: dzweSumI4bFxjlT8LApOVV
context:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/39/properties/content/properties/context'
- title: Task Due Date Updated
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: TASK/DUE_DATE_UPDATED
enum:
- TASK/DUE_DATE_UPDATED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- customerId
- taskId
- context
properties:
customerId:
type: string
description: The ID of the customer profile to which the task is associated.
example: gHufx-U3QqOmhvFuViceTw
taskId:
type: string
description: The ID of the task.
example: dzweSumI4bFxjlT8LApOVV
dueAt:
description: New time when the task will be due.
type: string
format: RFC3339
example: '2020-03-15T06:13:00.125Z'
context:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/39/properties/content/properties/context'
- title: Task Follower Added
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: TASK/FOLLOWER_ADDED
enum:
- TASK/FOLLOWER_ADDED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- customerId
- taskId
- agentId
- context
properties:
customerId:
type: string
description: The ID of the customer profile to which the task is associated.
example: gHufx-U3QqOmhvFuViceTw
taskId:
type: string
description: The ID of the task.
example: dzweSumI4bFxjlT8LApOVV
agentId:
type: string
description: ID of the agent who was added as a follower
example: zGaHXjD4SR-moMR9LbULDa
context:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/39/properties/content/properties/context'
- title: Task Follower Removed
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: TASK/FOLLOWER_REMOVED
enum:
- TASK/FOLLOWER_REMOVED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- customerId
- taskId
- agentId
- context
properties:
customerId:
type: string
description: The ID of the customer profile to which the task is associated.
example: gHufx-U3QqOmhvFuViceTw
taskId:
type: string
description: The ID of the task.
example: dzweSumI4bFxjlT8LApOVV
agentId:
type: string
description: ID of the agent who was removed as a follower
example: zGaHXjD4SR-moMR9LbULDa
context:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/39/properties/content/properties/context'
- title: Task Reopened
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: yHaHXjD4SR-moMR9LbULDb
type:
type: string
example: TASK/REOPENED
enum:
- TASK/REOPENED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- customerId
- taskId
- context
properties:
customerId:
type: string
description: The ID of the customer profile to which the task is associated.
example: gHufx-U3QqOmhvFuViceTw
taskId:
type: string
description: The ID of the task.
example: dzweSumI4bFxjlT8LApOVV
context:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/39/properties/content/properties/context'
responses:
'200':
description: Success
/api/v1/reports/work-session-events:
post:
tags:
- Reports
summary: Generate a Work Session Report
description: "> **Note:** This endpoint will generate the V2 version of the Work Session Report. Metrics may differ\
\ from the V4 version, used in the Gladly UI.\n> To generate a Work Sessions V4 Report, use the [Reports API](/rest/#tag/Reports).\n\
\nA **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:\n - A Customer may have 0 or more\
\ Conversations, but only 1 Conversation is open at any given time.\n - A Conversation may contain 0 or more Contacts\
\ (e.g.: A single phone call, a chat session, an email session).\n - A Contact may have 0 or more Work Sessions (i.e.:\
\ Agents who work on the Contact).\n - 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.\n\nThe 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.\n\nThe 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).\n\nThis means that if it is currently\
\ 2023-03-23T00:00Z and:\n - contact_session_id A was created on 2023-03-21T04:00Z and ended on 2023-03-22T04:00Z\n\
\ - You set the startAt time filter to 2023-03-21T00:00Z\n - You set the endAt time filter to 2023-03-22T00:00Z\n\
\ - 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.\n\nTherefore, 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.\n\nNote that:\n - 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\n - work_session_handle_time_sec will only be available for a contact after it ends\n -\
\ 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\n\nThis 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.\n - id\n - contact_session_id\n\
\ - contact_session_created_at\n - customer_id\n - conversation_id\n - inbox_id\n - channel\n - direction\n\
\ - agent_accepted_at\n - contact_session_routed_at\n - agent_id\n - sla_fulfilled_at\n - contact_session_ended_at\n\
\ - status\n - within_sla\n - work_session_handle_time_sec\n - work_session_after_contact_time_sec\n - work_session_unknown_time_sec\n\
\ - accepted_inbox_id\n"
requestBody:
description: A time range for the report that will be generated.
content:
application/json:
schema:
title: Work Session Report request body
type: object
required:
- startAtTime
- endAtTime
properties:
startAtTime:
type: string
description: 'Starting time of the report interval
The date should be in ISO 8601 format `YYYY-mm-ddThh:mmZ`. For example 2020-04-13T19:27Z
'
example: 2020-04-13T19:27Z
endAtTime:
type: string
description: 'Ending time of the report interval. This date is inclusive meaning that the report will include
data up to 1min past the endAtTime
The date should be in ISO 8601 format `YYYY-mm-ddThh:mmZ`. For example 2020-04-14T19:27-09:00
'
example: 2020-04-14T19:27-09:00
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:
description: Work Session Report CSV
format: binary
'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:
- name: startAt
required: true
in: query
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.
'
schema:
type: string
example: '2020-04-13T19:27:34-09:00'
- name: endAt
in: query
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.
'
required: false
schema:
type: string
example: '2020-04-13T20:27:12-09:00'
- name: entities
required: true
in: query
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`, `CUSTOMER_PROFILE`,
`PAYMENT_REQUEST`,`TASK`
'
schema:
type: array
example:
- AGENT_AVAILABILITY
- AGENT_STATUS
get:
tags:
- Events
summary: List Events
description: "Returns a stream of events for the specified entities within the given time range. Responses are streamed\
\ using JSONL.\n\nEvents are up to 15 seconds behind real-time. \n\n```\n/api/v1/events?startAt=2020-05-20T14:00:00Z&entities=AGENT_STATUS&entities=AGENT_AVAILABILITY\n\
```\n"
responses:
'200':
description: Events Streaming Response
content:
application/x-jsonlines:
schema:
title: Event Response Schemas
oneOf:
- title: Agent Availability Focus Entered
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: zGaHXjD4SR-moMR9LbULDa
type:
type: string
example: AGENT_AVAILABILITY/FOCUS_ENTERED
enum:
- AGENT_AVAILABILITY/FOCUS_ENTERED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
title: Content
description: Content for event
required:
- agentId
- context
properties:
agentId:
type: string
description: ID of the agent who entered or exited focus.
example: zGaHXjD4SR-moMR9LbULDa
context:
description: The state of the agent immediately before the event occurred.
required:
- availableFor
properties:
availableFor:
type: array
enum:
- MAIL
- MESSAGING
- TASK
- VOICE
description: 'The set of channel types for which the agent is available for.
'
example:
- MAIL
- TASK
- VOICE
- title: Agent Availability Focus Exited
type: object
required:
- id
- type
- timestamp
- initiator
- content
properties:
id:
type: string
description: Unique event ID
example: zGaHXjD4SR-moMR9LbULDa
type:
type: string
example: AGENT_AVAILABILITY/FOCUS_EXITED
enum:
- AGENT_AVAILABILITY/FOCUS_EXITED
timestamp:
type: string
format: ISO 8601
description: Time the event was recorded
example: '2019-07-03T04:30:12.07Z'
initiator:
$ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0/properties/initiator'
content:
$ref: '#/paths/~1api~1v1~1events/get/responses/200/content/application~1x-jsonlines/schema/oneOf/0/properties/content'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/0'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/1'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/2'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/3'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/4'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/5'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/6'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/7'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/8'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/9'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/10'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/11'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/12'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/13'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/14'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/15'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/16'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/17'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/18'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/19'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/20'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/21'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/22'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/23'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/24'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/26'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/27'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/28'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/29'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/30'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/32'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/36'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/37'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/38'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/39'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/40'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/41'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/42'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/43'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/44'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/45'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/46'
- $ref: '#/paths/~1gladly~1webhook/post/requestBody/content/application~1json/schema/oneOf/47'
'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:
type: http
scheme: basic
description: 'Gladly API uses token-based **Basic Authentication**. API tokens are associated with designated Gladly
users.
To create and use an API token, your user must have the API User permission. An API token can be used to perform any
API request without restriction.
| user name | password |
| ----------- | --------- |
| agent email | API token |
The credentials must be passed via an `Authorization` HTTP header. All requests must be made over HTTPS.
```shell
curl -u user@organization.com:$GLADLY_API_TOKEN \
https://organization.gladly.com/api/v1/organization
```
'
basicAuth:
type: http
scheme: basic
description: HTTP Basic auth — username is the API user email; password is the API token. Requires the "API User" permission.
schemas:
Error:
type: object
properties:
attr:
type: string
description: Identifies the field causing the error
code:
type: string
description: Code indicating the error type
detail:
type: string
description: More details describing what went wrong
Errors:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/Error'
example:
- attr: content
code: blank
detail: content cannot be blank
ErrorWithMeta:
allOf:
- $ref: '#/components/schemas/Error'
- type: object
properties:
meta:
type: object
additionalProperties: true
description: Additional information about the error
ErrorsWithMeta:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ErrorWithMeta'
example:
- attr: name
code: taken
detail: another entity with this name already exists
meta:
id: conflicting-id
NotFoundErrors:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/Error'
example:
- code: not_exist
detail: entity does not exist
security:
- basicAuth: []