# Gladly API - Complete Reference > This is the full Gladly developer API documentation in plain text, suitable for AI consumption. > Generated from the OpenAPI 3.0.1 specification. # 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 ## BasicAuth (http/basic) 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 ``` # API Resources ## Agents An **Agent** represents the user profile of a person who helps customers in Gladly. The API allows you to lookup Agents who participated in conversations with customers. ## Public Answer 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 ## Answer Management 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. One call to create an Answer and subsequent call(s) to add content(s) ## Audiences 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. ## Communications Communications API enables you to programmatically send messages to your customers. These messages are non-routable and non-searchable. ### Agent View ### Consumer View ## Customers 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. ## Conversations ## 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. ## Export 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. ## Endpoints An **Endpoint** represents an inbound address that customers use to reach your organization — for example an email address, a phone number, or a chat channel. Each endpoint has a `channel` describing the type of contact it receives (`EMAIL`, `SMS`, `VOICE`, `CHAT`, and so on). The Endpoints API is read-only. It allows you to retrieve the endpoints configured for your organization so you can programmatically discover which channels and addresses your organization is set up to receive customer contacts on. ## Events An **Event** is something that has happened in Gladly. The Events API allows you to extract event details from the past 24 hours. ## Freeform Topics Freeform Topics allow you to associate granular data like Order Number to a Conversation. This data can be accessed for analysis via APIs, Webhooks, and AWS EventBridge. They are powered by custom attributes as you will see throughout this API, the Conversations API, the Events API and events used in Webhooks. Note: These attributes are currently associated to the Conversation entity only and are therefore different from customAttributes listed under the Customer entity. See the Customer API for more information on Customer custom attributes. ## Reports A **Report** in Gladly contains metrics that you need to run the contact center. Reports API allows you to access Gladly's reports programatically. ## Organization An **Organization** contains metadata about your company that Gladly is configured with. ## Inboxes 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. ## Proactive Conversations 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. ## Tasks 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. ## Teams A **Team** represents a group of Agents. They may handle particular **Inboxes** or types of work within Gladly. ## Business Hours **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. ## Topics 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. ## Webhooks A **Webhook** is a way to send notifications about Gladly events as a POST request to the endpoint of your choice. ## Summary Gladly **webhooks** are an easy way to send notifications about Gladly events and have them delivered to the endpoint of your choice, giving you a streamlined method to trigger associated actions in external systems that respond to events in Gladly. Simply choose where to send notifications about events that you are interested in (e.g. when a conversation is closed), and they’ll be delivered to the endpoint of your choice. Configure webhooks using the [Webhooks API](#operation/createWebhook) or the Webhooks Admin Page. Users with API User permissions can configure webhooks by navigating to Integrations > Webhooks. ## Securing Webhooks We provide two methods for your web service to authenticate requests from Gladly. We recommend implementing at least one **authentication** option. ### Basic Authentication For this method you will supply a username and password with the webhooks `credentials` field. This will be sent with each request. You may optionally supply a realm if needed. ### Header Based Token Authentication For this method you will configure one or more HTTP headers with the webhook's `headers` field. Gladly will send in each request to your web service. ## Ping Event Whenever you enable a webhook or update a webhook's URL, we'll send you a special `PING` event. Your web service is expected to respond with a 200 status code to this event. If it does not respond or times out, the webhook create or update will not succeed. ## Retry Policy **Effective 6/28/23** If your service responds to an event with a response code outside the 2XX range or times out after 15 seconds, Gladly considers that delivery as failed and will resend the request up to 4 times over an hour. After the fourth attempt, we will deactivate the webhook and wil notify all API Users in your organization's environment via email. To reactivate the webhook, your team will first need to investigate the issue and make the necessary changes for the webhook to start working again. Once the issue is resolved, you will be able to re-activate the webhook via the Settings > Webhooks page. The following table shows the intervals between each retry attempt. | Attempt | Retry interval | | ------- | ------------------------ | | 1 | 30 seconds | | 2 | 5 minutes | | 3 | 30 minutes | | 4 | 1 hour | ## Logs We provide the last 100 HTTP request logs for a webhook that occurred during the past month. Logs can take up to 30 seconds to view and require you to refresh the page. Each log displays the status, event type and occurred at timestamp for a given request. You can expand the log for more details about the request and response. For more information about webhook logs, please see our [Help Documentation](https://connect.gladly.com/docs/help-documentation/article/reactivate-deactivated-webhooks/?highlight=webhook). ## Payloads Gladly payloads are intentionally small: they contain only Gladly IDs and event names rather than the object/data that has been modified or created This helps Gladly webhooks perform more quickly when many events occur throughout the day. This also assists with security, so if you misconfigure a webhook, it does not send sensitive information to an outside service. To retrieve more information about the object in question, you may make an additional Gladly API call to retrieve the Gladly object. For example, to know more about conversationId whose status was updated, call the [GET Conversation API](#operation/getConversation) or the [List Items in Conversation API](#operation/getConversationItems). ## Available Events Please see the [Help Documentation](https://help.gladly.com/docs/reporting-concepts) for more information about many of the events listed below. | Event | Triggered by Gladly when: | | ------------------------------| --------------------------------------------------------------| | AGENT_AVAILABILITY/UPDATED | an Agent's availability is updated | | AGENT_STATUS/CHANGED_ACTIVE_REASON | an Agent's active reason is updated | | AGENT_STATUS/LOGGED_IN | an Agent logs in | | AGENT_STATUS/LOGGED_OUT | an Agent logs out | | AGENT_STATUS/RETURNED_FROM_AWAY | an Agent returns from away | | AGENT_STATUS/WENT_AWAY | an Agent goes away | | CONTACT/ENDED | a Contact is ended | | CONTACT/FULFILLED | a Contact's SLA is fulfilled | | CONTACT/HOLD_ENDED | a Contact's hold is ended | | CONTACT/HOLD_STARTED | a Contact's hold is started | | CONTACT/JOINED | an Agent joins a Contact | | CONTACT/MESSAGE_RECEIVED | a Message is received | | CONTACT/MESSAGE_SENT | a Message is sent | | CONTACT/OFFER_ACCEPTED | a Contact's offer is accepted | | CONTACT/OFFERED | a Contact is offered | | CONTACT/OFFER_REJECTED | a Contact's offer is rejected | | CONTACT/STARTED | a Contact is started | | CONTACT/TRANSFERRED | a Contact is transferred | | CONVERSATION/CLOSED | a Conversation is closed | | CONVERSATION/CREATED | a new Conversation is created | | CONVERSATION/CUSTOM_ATTRIBUTE_ADDED | a custom attribute has been added to the conversation | | CONVERSATION/CUSTOM_ATTRIBUTE_REMOVED | a custom attribute has been removed from the conversation | | CONVERSATION/NOTE_CREATED | a Note is added to a Conversation | | CONVERSATION/REOPENED | a Conversation is reopened | CONVERSATION/TOPIC_ADDED | a topic is added to a Conversation | | CONVERSATION/TOPIC_REMOVED | a Conversation's topic is removed | | CONVERSATION_ASSIGNEE/UPDATED | a Conversation's assignee (inbox and/or Agent) changes | | CONVERSATION_STATUS/UPDATED | a Conversation changes statuses (e.g.: from OPEN to CLOSED) | | CUSTOMER/MERGED | a Customer Profile is merged with another profile | | CUSTOMER_PROFILE/CREATED | a Customer Profile is created | | CUSTOMER_PROFILE/DELETED | a Customer Profile is deleted | | CUSTOMER_PROFILE/MERGED | a Customer Profile is merged with another profile | | CUSTOMER_PROFILE/UPDATED | a Customer Profile is updated (e.g.: name is updated) | | EXPORT_JOB/COMPLETED | a [data export job](#operation/findJobs) is completed | | EXPORT_JOB/FAILED | a [data export job](#operation/findJobs) fails to complete | | PAYMENT_REQUEST/CREATED | a payment request is created | | PAYMENT_REQUEST/STATUS_CHANGED | a payment request's status changes | | PAYMENT_REQUEST/VIEWED | a payment request is viewed by the Customer | | PING | a webhook is initially created to verify serivce availability | | TASK/ASSIGNEE_UPDATED | a task's assignee is updated | | TASK/CLOSED | a task is closed | | TASK/COMMENT_ADDED | a comment is added to a task | | TASK/CONTENT_UPDATED | the content of a task is updated | | TASK/CREATED | a task is created | | TASK/DUE_DATE_UPDATED | the due date of a task is updated | | TASK/FOLLOWER_ADDED | a follower is added to a task | | TASK/FOLLOWER_REMOVED | a follower is removed from a task | TASK/REOPENED | a closed task is reopened | ## Customer Lookup **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). ## Versioning 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)**), or result in a new version that you will need to integrate with afresh (i.e. **[non-backwards compatible changes](#non-backwards-compatible-changes)**). ## URL Path Versioning The various versions of the Gladly API will be differentiated via global versioning, with the relevant version number reflected within the path parameter of the URL: https://organization.gladly.com/api/v{major-version-number}/{resource path} ## Backwards Compatible Changes For the most part, changes to the API will be backwards compatible, such as adding resources, additional fields to response objects, new value types for enums, or expanding a validation constraint to be more accepting. Ensure your client can gracefully handle or ignore unfamiliar fields and values so it continues to operate smoothly over the lifespan of an API version. ## Non-Backwards Compatible Changes Versions will be upleveled when a non-backwards compatible change occurs. This should not happen often, but can occur in the case of: - a field being removed from an object - a resource path no longer being supported - changing the type of a field - adding a new required parameter for a resource - constricting the validation parameters for a request These will only occur when absolutely necessary and a summary of the changes from version to version can be viewed in the release notes. Previous versions will be supported for a period of time before being removed after providing ample advanced notice. ## Error Handling Wherever possible, Gladly uses standard HTTP status codes to signal the success or failure of a call. Generally speaking, `2xx` statuses indicate success, `3xx` statuses indicate the client must take further action such as redirection, `4xx` statuses indicate an error with the input supplied by the client, `5xx` statuses indicate an unexpected error from Gladly servers (these will be rare cases). ## Common Status Codes | HTTP Status | Description | | ----------- | ------------------------------------------------- | | 200 | Success with results in response body | | 201 | Resource created | | 204 | Success with empty response body | | 301 | The resource location has moved | | 400 | API usage error | | 401 | Authentication not provided | | 403 | User does not have persmission to access resource | | 404 | Resource is not found | | 429 | Rate limit reached | ## Programmatic Remediation In the case of a `400` response, there will be a structured list of `error` objects that will provide information to correct the error. The error object will contain a `code` to describe the problem. The most common codes are: | Code | Description | | ------------ | -------------------------------------- | | blank | Presence error | | invalid | Format error | | moved | This resource is now located elsewhere | | not_a_number | Value not numeric error | | present | Absence error | | taken | Uniqueness error | | too_long | Exceeds permissible length error | | wrong_length | Length is not equal to expected error | Refer to the errors section of each endpoint for more information. Example: {"errors":[{"code":"blank","detail":"one of emailAddress, phoneNumber must be present"}]} ## Rich Content 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`. ## Launching Soon 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. ## Rate Limit 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. Gladly has two types of API rate limits: ### Request Limit Request 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. ### Concurrency Limit Concurrency 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. ## Default Rate Limit Organizations that send many requests in quick succession may see error responses that show up as status code **`429`**. >Individual APIs may have their own API Rate Limit and will be documented as such. Otherwise, the following default rate limits apply. | Method | Request Limit | Concurrency Limit | | ------------------- | -----------------------------------|----------------------------------| | GET | 10 Requests per second | Not Applicable | | POST | 10 Requests per second | Not Applicable | | PUT | 10 Requests per second | Not Applicable | | PATCH | 10 Requests per second | Not Applicable | | DELETE | 10 Requests per second | Not Applicable | We may adjust limits to prevent abuse. If you have questions about rate limited requests, please contact [Gladly Support](https://help.gladly.com/docs/contact-gladly-support). ## Reporting API Rate Limit The [Reports](#tag/Reports) APIs have slightly different default rate limits than other APIs. | Method | Request Limit | Concurrency Limit | | ------------------- | -----------------------------------|----------------------------------| | POST | 10 Requests per minute | 2 concurrent requests at a time across the entire organization | ## Handling Rate Limit The Gladly API response headers include the organization's current rate limit and the number of requests remaining in the current second. The remaining limit is calculated using the total number of requests received from all clients with your organization's API tokens. ```json Ratelimit-Limit-Second Ratelimit-Remaining-Second ``` You can anticipate hitting the rate limit by checking these headers. One 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. We’d also recommend building some randomness into the backoff schedule to avoid a **[thundering herd effect](https://en.wikipedia.org/wiki/Thundering_herd_problem)**. # API Endpoints ## POST /api/v1/communications/sms Tags: Communications Summary: Send SMS Operation ID: sendSMS To send an SMS message to a customer specified by a mobile phone number. Gladly can send outbound SMS messages globally. By default, your organization is set up to only allow access to your home country. To send SMS messages to other countries, please contact [Gladly Support](https://help.gladly.com/implementation/docs/filing-a-support-issue) with a P4 designation. Please be aware that: - Any automated outbound text messages **must** comply with carrier [acceptable use policies](https://help.gladly.com/docs/sms-compliance-requirements) (e.g.: if sending automated messages about order status, make sure customers can explicitly opt-in to text messages), including registering your SMS use cases carriers. - Text messages send in [segments](https://help.gladly.com/v1/docs/en/voice-and-sms-phone-number-costs) and you pay per segment. We highly recommend using the [segment calculator](https://twiliodeved.github.io/message-segment-calculator/) when crafting automated outbound text messages. - Each type of phone number has a [Message Segments per Second limit](https://support.twilio.com/hc/en-us/articles/115002943027-Understanding-Twilio-Rate-Limits-and-Message-Queues). Request Body: SMS to send Content-Type: application/json Responses: 200: the customer and conversation item ID 400: Invalid field(s) in request body --- ## POST /api/v1/communications/email Tags: Communications Summary: Send email Operation ID: sendEmail 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. Request Body: Email to send Content-Type: application/json Responses: 200: the customer and conversation item ID 400: Invalid field(s) in request body --- ## GET /api/v1/customers/{customerId}/conversations Tags: Conversations Summary: Get conversations for customer Operation ID: getConversations Get the list of conversations for a customer. The list is not paginated and will return at most 100 conversations. The conversations are returned in ascending order by timestamp. The `Gladly-Limited-Data` header flag in the response will indicate if the customer has more conversations than returned. Parameters: - customerId [path]: string (required) - Id of the customer to get all conversations for Responses: 200: The conversations for the customer --- ## GET /api/v1/conversations/{conversationId} Tags: Conversations Summary: Get conversation Operation ID: getConversation Get conversation metadata such as it's assignee, topics, inbox, etc. Parameters: - conversationId [path]: string (required) - Id of the conversation to get Responses: 200: Conversation metadata 404: A conversation with the given id does not exist --- ## PATCH /api/v1/conversations/{conversationId} Tags: Conversations Summary: Update conversation Operation ID: patchConversation Update conversation assignee, statusor both Parameters: - conversationId [path]: string (required) - Id of the conversation Request Body: JSON representation of conversation updates Content-Type: application/json Responses: 204: updated conversation 400: Invalid request 404: A conversation with the given id does not exist --- ## POST /api/v1/conversation-items Tags: Conversations Summary: Create item Operation ID: createItem To add items to the timeline for a customer specified by identifying information. If the customer doesn't exist, a new customer profile is created. Any items created using this API will not be considered part of a conversation, and are **non-routable** and **non-searchable** aside from the mobile phone number or email address specified as part of the payload. Request Body: Conversation Item to create Content-Type: application/json Responses: 200: The created item 400: Invalid field(s) in request body 409: Specified id is in use --- ## GET /api/v1/conversation-items/{itemId} Tags: Conversations Summary: Get item Operation ID: getItem Returns the conversation item with the provided id. Parameters: - itemId [path]: string (required) - id of the conversation item Responses: 200: conversation item 400: An item exists but is not supported by the API 404: An item with the given id could not be found --- ## DELETE /api/v1/conversation-items/{itemId} Tags: Conversations Summary: Delete item Operation ID: deleteItem To delete an item. Please note only items of type **CUSTOMER_ACTIVITY** may be deleted by this API. Parameters: - itemId [path]: string (required) - Id of the item to be deleted. Responses: 204: The item was deleted 404: An item with the given id could not be found --- ## GET /api/v1/conversation-items/{itemId}/media/recording Tags: Conversations Summary: Get media Operation ID: getMedia Returns the media file associated with the conversation item Parameters: - itemId [path]: string (required) - id of the conversation item Responses: 200: The media file associated with the conversation item 404: An item with the given id could not be found --- ## GET /api/v1/conversation-items/{itemId}/voice-transcript Tags: Conversations Summary: Get voice transcript Operation ID: getVoiceTranscript Returns a transcript of a phone call or a voicemail Parameters: - itemId [path]: string (required) - id of the conversation item Responses: 200: The voice transcript of a phone call or a voicemail 404: A transcript with the given id could not be found --- ## GET /api/v1/conversation-items/{itemId}/attachments/{attachmentId} Tags: Conversations Summary: Get attachment Operation ID: getAttachment 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. Parameters: - itemId [path]: string (required) - Id of the conversation item that contains the attachment. - attachmentId [path]: string (required) - Id of the attachment to retrieve. Responses: 303: Redirect to the attachment URL 400: The conversation item content does not contain attachments 404: The conversation item or attachment could not be found --- ## POST /api/v1/customers/{customerId}/conversation-items Tags: Conversations Summary: Create item for customer Operation ID: createCustomerItem To add items to a customer's timeline. Any items created using this API will not be considered part of a conversation, and are **non-routable** and **non-searchable** aside from the mobile phone number or email address specified as part of the payload. Parameters: - customerId [path]: string (required) - Id of the customer associated with this item. Request Body: Conversation Item to create Content-Type: application/json Responses: 200: The created item 301: This customer id no longer exists, but has been moved because it has been merged with another customer 400: Invalid field(s) in request body 404: Customer with customerId does not exist 409: Specified id is in use --- ## DELETE /api/v1/customers/{customerId}/conversation-items/{itemId} Tags: Conversations Summary: Delete item for customer Operation ID: deleteCustomerItem To delete an item. Please note only items of type **CUSTOMER_ACTIVITY** may be deleted by this API. Parameters: - customerId [path]: string (required) - Id of the customer associated with this item. - itemId [path]: string (required) - Id of the item to be deleted. Responses: 204: The item was deleted 404: An item with the given id, for the given customer id, could not be found --- ## GET /api/v1/conversations/{conversationId}/items Tags: Conversations Summary: List items in conversation Operation ID: getConversationItems 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. Parameters: - conversationId [path]: string (required) - Id of the conversation to get the timeline for - sessionId [query]: string - Return only items whose `sessionId` matches the given value. Responses: 200: The items on the conversation timeline 404: A conversation with the given id does not exist --- ## POST /api/v1/conversations/{conversationId}/topics Tags: Conversations Summary: Add Topics to Conversation Operation ID: addTopicToConversation Adds a list of topics to the conversation. If a topic being added already exists on the conversation, that topic is ignored. Parameters: - conversationId [path]: string (required) - Id of the conversation. Request Body: Content-Type: application/json Responses: 204: The topic was added successfully 400: Invalid field(s) in request body 404: A conversation with the given Id could not be found --- ## DELETE /api/v1/conversations/{conversationId}/topics/{topicId} Tags: Conversations Summary: Delete Topic from Conversation Operation ID: deleteTopicFromConversation Delete a topic from a conversation. Parameters: - conversationId [path]: string (required) - Id of the conversation. - topicId [path]: string (required) - Id of topic to be deleted from conversation. Responses: 204: The topic was deleted from the conversation successfully 404: A conversation with the given id could not be found --- ## POST /api/v1/customer-history/{customerId}/conversations/{conversationId}/custom-attributes Tags: Conversations Summary: Add or Remove Freeform topic 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: - customerId [path]: string (required) - Id of the customer. - conversationId [path]: string (required) - Id of the conversation. Request Body: Content-Type: application/json Responses: 204: The freeform topic was added successfully 400: Invalid field(s) in request body 404: A conversation with the given Id could not be found --- ## POST /api/v1/conversations/{conversationId}/notes Tags: Conversations Summary: Add note Operation ID: addNoteToConversation Adds note to an existing conversation. Parameters: - conversationId [path]: string (required) - Id of the conversation. Request Body: Content-Type: application/json Responses: 201: The note was added successfully 400: Invalid field(s) in request body 404: A conversation with the given Id could not be found --- ## GET /api/v1/conversations/{conversationId}/notes/{noteId} Tags: Conversations Summary: Get note Operation ID: getNoteFromConversation Returns the note with the provided conversation and note id. Parameters: - conversationId [path]: string (required) - id of the conversation - noteId [path]: string (required) - id of the note Responses: 200: Conversation note 404: An item with the given id could not be found --- ## POST /api/v1/conversation-items/{itemId}/reply Tags: Conversations Summary: Reply to message Operation ID: replyToMessage 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. Parameters: - itemId [path]: string (required) - id of the conversation item Request Body: Content-Type: application/json Responses: 201: The reply was created successfully. Note that creation doesn't guarantee delivery 400: Invalid field(s) in request body 404: A conversation item with the given id could not be found --- ## POST /api/v1/conversation-items/{itemId}/redact Tags: Conversations Summary: Redact conversation item Operation ID: redactContent For supported items, the item's content will be removed but the item will remain in the conversation timeline. Supported types are Chat Message, SMS Message, Email, Twitter (decommissioned as of 04/20/23, but can still be redacted), WhatsApp, Voicemail, Phone Call. Parameters: - itemId [path]: string (required) - id of the conversation item Request Body: Content-Type: application/json Responses: 201: The redaction was successful. 404: A conversation item with the given id could not be found --- ## POST /api/v1/tasks Tags: Tasks Summary: Create task Operation ID: createTaskAndCustomer 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. Request Body: Task to create Content-Type: application/json Responses: 201: task created 400: Invalid field(s) in request body --- ## GET /api/v1/customers/{customerId}/tasks Tags: Tasks Summary: List tasks Operation ID: getTasks Fetch all tasks for a customer. The list is not paginated and will return at most 2000 tasks. The tasks are returned in descending order by timestamp. The `Gladly-Limited-Data` header flag in the response will indicate if the customer has more tasks than returned. To see and act on any newly created tasks, webhooks can be used to listen for task related events. Tasks older than the limit can be viewed using the Task Export. Parameters: - customerId [path]: string (required) - Id of the customer whose tasks you'd like to view. - status [query]: string - Fetch tasks with the provided status. Responses: 200: Array of tasks 400: Invalid input 404: A customer with the given id does not exist --- ## POST /api/v1/customers/{customerId}/tasks Tags: Tasks Summary: Create task for customer Operation ID: createTask Add a task to an existing customer's conversation timeline Parameters: - customerId [path]: string (required) - Id of the customer associated with the task to create. Request Body: Create Task Content-Type: application/json Responses: 201: task created 400: Invalid field(s) in request body 404: Customer with customerId does not exist 409: Specified id is in use --- ## GET /api/v1/tasks/{taskId} Tags: Tasks Summary: Get task Operation ID: getTask Get task Parameters: - taskId [path]: string (required) - Id of the task requested Responses: 200: Returns requested task 404: Given task id does not exist --- ## PATCH /api/v1/tasks/{taskId} Tags: Tasks Summary: Update task Operation ID: updateTask Update an existing task Parameters: - taskId [path]: string (required) - Id of the task that is to be updated Request Body: Task properties to create Content-Type: application/json Responses: 204: The task was created task 400: Invalid field(s) in request body 404: Task with taskId does not exist. --- ## GET /api/v1/tasks/{taskId}/comments Tags: Tasks Summary: Get task comments Operation ID: getTaskComments The comments are returned in ascending order by createdAt timestamp. The list is not paginated and will return at most 1000 task comments. The `Gladly-Limited-Data` header flag in the response will indicate if the task has more comments than returned. To see and act on any newly created task comments, webhooks can be used to listen to any task comment related events. Parameters: - taskId [path]: string (required) - Id of the task comments are requested for. Responses: 200: All comments that belong to task 404: Task with taskId does not exist --- ## POST /api/v1/tasks/{taskId}/comments Tags: Tasks Summary: Add task comment Operation ID: createTaskComment Create a comment on a task. Note that you can’t create comments on closed tasks. Parameters: - taskId [path]: string (required) - Id of the task that will be commented on. Request Body: Add comment to task Content-Type: application/json Responses: 201: comment added 400: Invalid field(s) in request body 404: Task with taskId does not exist --- ## GET /api/v1/tasks/{taskId}/comments/{commentId} Tags: Tasks Summary: Get task comment Operation ID: getTaskComment Get task comment. Parameters: - taskId [path]: string (required) - Task id - commentId [path]: string (required) - Comment id Responses: 200: Returns task comment 404: Comment with commentId does not exist --- ## GET /api/v1/custom-attributes/:customAttributeId Tags: Freeform Topics Summary: Get custom attribute Operation ID: getCustomAttribute Returns a custom attribute that matches the provided custom attribute id. Parameters: - customAttributeId [path]: string (required) - id of the custom attribute Responses: 200: 404: Custom Attribute not found --- ## GET /api/v1/customer-profiles Tags: Customers Summary: Find customers Operation ID: findCustomers Find customers by searching by choosing **one** of the following identifiers as query parameters: ``` /api/v1/customer-profiles?phoneNumber=%2B14151234567 ``` Max limit of 50 profiles returned, sorted by most recently updatedAt date descending. Parameters: - email [query]: string - customer email address to search on. - externalCustomerId [query]: string - 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. - phoneNumber [query]: string - Phone number in E.164 format. The value should be URL escaped where `+` becomes `%2B`. Responses: 200: found customers Type: array Items: 400: error finding customers --- ## POST /api/v1/customer-profiles Tags: Customers Summary: Create customer Operation ID: createCustomer Create a new customer with the supplied profile data. Request Body: Customer record to add. Content-Type: application/json Responses: 201: customer created 400: error creating customer 409: Specified id is in use or a uniqueness constraint failed --- ## GET /api/v1/customer-profiles/{customerId} Tags: Customers Summary: Get customer Operation ID: getCustomer 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. Parameters: - customerId [path]: string (required) - id of the customer Responses: 200: fetched customer 301: customer id no longer exists and has been changed due to a merge with another customer 404: customer not found --- ## PATCH /api/v1/customer-profiles/{customerId} Tags: Customers Summary: Update customer Operation ID: updateCustomer 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. Parameters: - customerId [path]: string (required) - id of the customer Request Body: JSON patch of customer profiles properties to insert or update. Content-Type: application/json Responses: 204: updated customer 400: error updating customer 404: customer not found --- ## DELETE /api/v1/customer-profiles/{customerId} Tags: Customers Summary: Delete customer Operation ID: deleteCustomer 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. Parameters: - customerId [path]: string (required) - id of the customer Responses: 204: customer was deleted 400: error deleting customer with open or waiting conversation --- ## POST /api/v1/user-identity-jwt Tags: User Identity Summary: Create a User Identity JWT Operation ID: createUserIdentityJWT Create a User Identity JWT for a customer. The JWT is used to authenticate the customer with [Chat](https://developer.gladly.com/chat/). The JWT contains the customer identity information. Request Body: Customer Identity Information Content-Type: application/json Responses: 200: customer created Type: object Properties: - token: string - The JWT created 400: error creating JWT --- ## GET /api/v1/orgs/{orgId}/answers-search?q=search+terms Tags: Public Answer Summary: Search public answers Operation ID: searchAnswers Returns a list of answers that match the provided query string. Parameters: - orgId [path]: string (required) - id of your organization - q [query]: string - search term - lng [query]: string - language code - audienceId [query]: string - 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. Responses: 200: found answers Type: array Items: --- ## GET /api/v1/orgs/{orgId}/answers?lng={lng}&audienceId={audienceId} Tags: Public Answer Summary: List public answers Operation ID: listAnswers Returns the first 1000 public answers sorted alphabetically by name. Parameters: - orgId [path]: string (required) - id of your organization - lng [query]: string - Language of the answers returned - audienceId [query]: string - 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. Responses: 200: answers Type: array Items: --- ## GET /api/v1/orgs/{orgId}/help-center/{helpCenterId}/answer-titles?lng={lng}&audienceId={audienceId} Tags: Public Answer Summary: List Help Center Answer Titles Operation ID: getAnswerTitles Returns an array of answers configured in Help Center sections with their ID and name Parameters: - orgId [path]: string (required) - id of your organization - helpCenterId [path]: string (required) - Help Center ID - lng [query]: string - Language of the answers returned - audienceId [query]: string - 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. Responses: 200: answers Type: array Items: --- ## GET /api/v1/orgs/{orgId}/answers/{answerId} Tags: Public Answer Summary: Get public answer Operation ID: getAnswer Returns the answer with the provided id. Parameters: - orgId [path]: string (required) - id of your organization - answerId [path]: string (required) - id of the answer - lng [query]: string - language code Responses: 200: answer --- ## GET /api/v1/answers Tags: Answer Management Summary: Get answers Operation ID: getAnswers Returns every answer in the org, including the `availableContents` discovery map on each. Intended as the entry point for syncing answers to an external system. Unlike [List public answers](#operation/listAnswers) (which lists help-center public answers in a single language), this endpoint returns all answers regardless of content type or language. Responses: 200: answers Type: array Items: --- ## POST /api/v1/answers Tags: Answer Management Summary: Add answer Operation ID: addAnswer Adds an answer to the list of answers. Request Body: Content-Type: application/json Responses: 200: Added answer 400: Bad Request 409: Specified id is in use --- ## GET /api/v1/answers/{answerId} Tags: Answer Management Summary: Get Answer Operation ID: getAnswerById Returns the answer requested. Parameters: - answerId [path]: string (required) - id of the answer Responses: 200: answer 404: Answer does not exist --- ## PATCH /api/v1/answers/{answerId} Tags: Answer Management Summary: Update Answer Operation ID: updateAnswer Updates the answer with the provided id. Parameters: - answerId [path]: string (required) - id of the answer Request Body: Content-Type: application/json Responses: 204: Answer updated 400: Bad Request 404: Answer does not exist --- ## DELETE /api/v1/answers/{answerId} Tags: Answer Management Summary: Delete Answer Operation ID: deleteAnswer Deletes the answer with the provided id. Parameters: - answerId [path]: string (required) - id of the answer Responses: 204: Answer deleted 400: Bad Request 404: Answer does not exist --- ## GET /api/v1/answers/{answerId}/languages/{language}/type/{type} Tags: Answer Management Summary: Get Answer Content Operation ID: getAnswerContentByLanguageAndType Returns the answer content requested by language and type. **Note:** For `email` type answers, if the subject line is empty, the API will return `204 No Content` instead of a response body. Parameters: - answerId [path]: string (required) - id of the answer - language [path]: string (required) - Language code according to ISO 639 format. The specified language must also be configured for the org. - type [path]: string (required) - Type of answer. Must be one of `public`, `email`, `messaging`, or `reference`. Responses: 200: answerContent 204: No content. Returned for email type answers when the subject line is empty. 400: Bad Request 404: Answer content does not exist --- ## PUT /api/v1/answers/{answerId}/languages/{language}/type/{type} Tags: Answer Management Summary: Add or Update Answer Content Operation ID: addAnswerContentByLanguageAndType Adds or Updates the answer content for the specified answer by language and type. Parameters: - answerId [path]: string (required) - id of the answer - language [path]: string (required) - Language code according to ISO 639 format. The specified language must also be configured for the org. - type [path]: string (required) - Type of answer. Must be one of `public`, `email`, `messaging`, or `reference`. Request Body: The request body fields depend on the content type: Content-Type: application/json Responses: 200: Added/Updated answer content 400: Bad Request 404: Answer does not exist --- ## DELETE /api/v1/answers/{answerId}/languages/{language}/type/{type} Tags: Answer Management Summary: Delete Answer Content Operation ID: deleteAnswerContentByLanguageAndType Deletes the answer content for the specified answer by language and type. Parameters: - answerId [path]: string (required) - id of the answer - language [path]: string (required) - Language code according to ISO 639 format. The specified language must also be configured for the org. - type [path]: string (required) - Type of answer. Must be one of `public`, `email`, `messaging`, or `reference`. Responses: 204: Answer content deleted 400: Bad Request One of: 404: Does not exist --- ## GET /api/v1/agents Tags: Agents Summary: List Agents Operation ID: getAgents Returns a list of agents. Responses: 200: Agents --- ## GET /api/v1/agents/{agentId} Tags: Agents Summary: Get Agent Operation ID: getAgent Get an agent profile by their unique id. Parameters: - agentId [path]: string (required) - id of the agent Responses: 200: Agent --- ## GET /api/v1/agents/{agentId}/call-recorder Tags: Agents Summary: Get Agent CallRecorder Operation ID: getAgentCallRecording Get an agent call recording status. Parameters: - agentId [path]: string (required) - Gladly ID or Gladly email address of the agent Responses: 200: CallRecorder 404: Agent not found --- ## PATCH /api/v1/agents/{agentId}/call-recorder Tags: Agents Summary: Update Agent CallRecorder Operation ID: updateAgentCallRecording Update an agent's active call recording status. This API allows changing the `recording` property. Parameters: - agentId [path]: string (required) - Gladly ID or Gladly email address of the agent Request Body: JSON patch of CallRecorder Content-Type: application/json Responses: 204: Call recording updated. If an agent is not on a call the update will do nothing. 404: Agent not found --- ## GET /api/v1/audiences Tags: Audiences Summary: List Audiences Operation ID: getAudiences Returns a list of audiences. Responses: 200: Audiences --- ## GET /api/v1/business-hours Tags: Business Hours Summary: List business hours Operation ID: getBusinessHours Returns a list of all business hours configurations for your organization. Responses: 200: Business hours --- ## POST /api/v1/business-hours Tags: Business Hours Summary: Create business hours Operation ID: createBusinessHours Creates a new business hours configuration for your organization. Request Body: Business hours configuration to create Content-Type: application/json Responses: 201: Business hours created 400: Validation error --- ## GET /api/v1/business-hours/{businessHoursId} Tags: Business Hours Summary: Get business hours Operation ID: getBusinessHoursById Returns a single business hours configuration by its unique ID. Parameters: - businessHoursId [path]: string (required) - ID of the business hours configuration Responses: 200: Business hours 404: Business hours not found --- ## PUT /api/v1/business-hours/{businessHoursId} Tags: Business Hours Summary: Update business hours Operation ID: updateBusinessHours Updates an existing business hours configuration. The `version` field must match the current version of the business hours to prevent conflicting updates. Parameters: - businessHoursId [path]: string (required) - ID of the business hours configuration Request Body: Updated business hours configuration Content-Type: application/json Responses: 200: Business hours updated 400: Validation error 404: Business hours not found 409: Version conflict --- ## DELETE /api/v1/business-hours/{businessHoursId} Tags: Business Hours Summary: Delete business hours Operation ID: deleteBusinessHours Deletes a business hours configuration. The primary business hours configuration cannot be deleted. Parameters: - businessHoursId [path]: string (required) - ID of the business hours configuration Responses: 204: Business hours deleted 400: Cannot delete primary business hours 404: Business hours not found --- ## GET /api/v1/organization Tags: Organization Summary: Get organization Operation ID: getOrganization Returns metadata about your organization. Responses: 200: Organization --- ## GET /api/v1/inboxes Tags: Inboxes Summary: List inboxes Operation ID: getInboxes Returns a list of inbox metadata. Responses: 200: Inboxes --- ## GET /api/v1/inboxes/{inboxId} Tags: Inboxes Summary: Get inbox Operation ID: getInbox Get the metadata for an inbox by its unique id. Parameters: - inboxId [path]: string (required) - id of the inbox Responses: 200: Inbox --- ## POST /api/v1/inboxes/{inboxId}/agents Tags: Inboxes Summary: Add or remove inbox agents Operation ID: updateInboxAgents Adds and/or removes agents from an inbox in a single request. The resulting membership is the inbox's current agents, plus the agents in `add`, minus the agents in `remove`. At least one of `add` or `remove` must contain at least one agent id. A maximum of 100 agent ids may be changed per request (across both lists combined), and an agent id may not appear in both `add` and `remove`. Every agent id in `add` must belong to an agent in your organization; ids in `remove` are not checked for existence. Parameters: - inboxId [path]: string (required) - id of the inbox Request Body: The agent ids to add to and/or remove from the inbox. At least one of `add` or `remove` must be non-empty. Content-Type: application/json Responses: 204: The inbox agents were updated successfully 400: Invalid field(s) in request body, for example an empty request, more than 100 agent ids, or an unknown agent id in `add` 404: An inbox with the given id could not be found 409: The same agent id appears in both `add` and `remove` --- ## GET /api/v1/teams Tags: Teams Summary: List teams Operation ID: getTeams Returns a list of teams. Responses: 200: Teams --- ## GET /api/v1/teams/{teamId} Tags: Teams Summary: Get team Operation ID: getTeam Get a team by its unique id. Parameters: - teamId [path]: string (required) - id of the team Responses: 200: Team --- ## GET /api/v1/topics Tags: Topics Summary: List Topics Operation ID: getTopics Returns a list of Topics. Responses: 200: Topics --- ## POST /api/v1/topics Tags: Topics Summary: Add Topic Operation ID: addTopic Add a Topic to the list of available Topics. Request Body: Topic to create Content-Type: application/json Responses: 201: Topic Created 400: Bad Request 409: Topic contains conflicting values --- ## GET /api/v1/topics/{topicId} Tags: Topics Summary: Get Topic Operation ID: getTopic Get a Topic by its unique id. Parameters: - topicId [path]: string (required) - id of the Topic Responses: 200: Topic 404: Given Topic id does not exist --- ## PATCH /api/v1/topics/{topicId} Tags: Topics Summary: Update Topic Operation ID: updateTopic Update an existing Topic. Parameters: - topicId [path]: string (required) - id of the Topic Request Body: Content-Type: application/json Responses: 204: Topic updated successfully 400: Bad Request 404: Topic with the specified id does not exist 409: Topic update contains conflicting values --- ## GET /api/v1/export/schedules Tags: Export Summary: List schedules Operation ID: findSchedules List all schedules. Currently, only one schedule can be configured per organization. The schedule will generate recurring data export jobs with an hourly or daily frequency. By default, each organization has a daily export job configured. To change the job frequency, please contact Gladly Support. Hourly schedules generate new jobs on a roughly two hour lag after the `nextStartAt` time. For example, for an hourly schedule with a `nextStartAt` equal to `2019-01-21T08:00:00.00Z`, the next job will be created at approximately `2019-01-21T10:00:00.00Z`. Daily schedules will run jobs during the night (UTC time). Responses: 200: found jobs Type: array Items: --- ## GET /api/v1/export/jobs Tags: Export Summary: List jobs Operation ID: findJobs List all jobs for the organization in any status for the last 14 days. ``` /api/v1/export/jobs ``` You can further filter the results by including query parameters for `status`, `startAt`, and `endAt`. ``` /api/v1/export/jobs?status=COMPLETED&startAt=2024-09-15T00:00:00.000Z&endAt=2024-09-16T00:00:00.000Z ``` Parameters: - status [query]: string - export job status to search on. - startAt [query]: string - 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. - endAt [query]: string - 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. Responses: 200: found jobs Type: array Items: --- ## GET /api/v1/export/jobs/{jobId} Tags: Export Summary: Get job Operation ID: getJob Get a job by unique id. Parameters: - jobId [path]: string (required) - id of the job Responses: 200: fetched job 404: job not found --- ## DELETE /api/v1/export/jobs/{jobId} Tags: Export Summary: Delete job Operation ID: deleteJob Delete a job and all associated files. *Note*: job status must be `COMPLETED` or `FAILED` to be deleted. Parameters: - jobId [path]: string (required) - id of the job Responses: 204: the job was deleted 400: unable to delete job 404: job not found --- ## GET /api/v1/export/jobs/{jobId}/files/{filename} Tags: Export Summary: Get file Operation ID: getFile Download a file generated by a data export job. Filenames can be found from an export [job's](index.html#operation/getJob) `files` field. Files are returned in `.jsonl` format where each line is a `json` object representing an element from the array of data. Please note that, in rare cases, conversation items with invalid attributes may be excluded from the data export. For example: - An email message that was undelivered due to an invalid recipient email address - EMAIL / SMS auto-replies sent by Gladly to the customer via a Rule Examples are as follows with schema below. **agents.jsonl** ``` {"id": "WmeA3Y51Q5ayCAaZ1AotIA","name": "Amy Agent","emailAddress": "amy.agent@company.com"} ``` **conversation_items.jsonl** ``` {"id": "ybP4szYCSy6LdV4DNwEd6g","conversationId": "9BcE2O0DQ2ynGHRmk9FeoA","customerId": "OOrlNMXeS72gs_WEX2TtMg","timestamp": "2019-07-01T11:46:45.010Z","initiator": {"id": "OOrlNMXeS72gs_WEX2TtMg","type": "CUSTOMER"},"content": {"type": "CHAT_MESSAGE","sessionId": "5k04bYuTRGqyT6uoSQfWVA","content": "Hi! I know it's after hours but can someone help upgrade my account?"}} {"id": "9lQDrx-HTz-JMoP2T4CtZA","conversationId": "9BcE2O0DQ2ynGHRmk9FeoA","customerId": "OOrlNMXeS72gs_WEX2TtMg","timestamp": "2019-07-02T06:30:12.070Z","initiator": {"id": "WmeA3Y51Q5ayCAaZ1AotIA","type": "AGENT"},"content": {"type": "EMAIL","from": "amy.agent@company.com","to": ["martha.williams@gmail.com"],"subject": "Account upgrade","content": "I would be happy to help you! We need a few details, so please give us a call this morning."}} {"id": "QN1nURRuRne_eAEhW45UMA","conversationId": "9BcE2O0DQ2ynGHRmk9FeoA","customerId": "KgnVOMc2TbiA3zad6iVlWA","timestamp": "2020-04-21T00:44:33.690Z","initiator": {"type":"AGENT","id":"VjeJI9_GRUS_LUjKLcNlBw"},"responder":{"type":"CUSTOMER","id":"KgnVOMc2TbiA3zad6iVlWA"},"content":{"startedAt":"2020-04-21T00:44:34.604Z","answeredAt":"2020-04-21T00:44:45.515Z","completedAt":"2020-04-21T00:44:57.130Z","from":"+12096248260","to":"+14155335980","recordingUrl":"/api/v1/conversation-items/QN1nURRuRne_eAEhW45UMA/media/recording","recordingStatus":"AVAILABLE","recordingDuration":11,"type":"PHONE_CALL"}} {"id": "K0UGL3n6S4uPpvtMvItqHA","conversationId": "9BcE2O0DQ2ynGHRmk9FeoA","customerId": "OOrlNMXeS72gs_WEX2TtMg","timestamp": "2019-07-02T08:12:55.870Z","initiator": {"id": "WmeA3Y51Q5ayCAaZ1AotIA","type": "AGENT"},"content": {"type": "TOPIC_CHANGE","addedTopicIds": ["uu4t00vITaKQ3bVjU2UrGQ"]}} {"id": "VMn_5L1iTPmcM5DBP1U8oQ","conversationId": "9BcE2O0DQ2ynGHRmk9FeoA","customerId": "KgnVOMc2TbiA3zad6iVlWA","timestamp": "2020-04-21T00:56:03.712Z","initiator": {"type":"CUSTOMER","id":"KgnVOMc2TbiA3zad6iVlWA"}, "content":{"startedAt":"2020-04-21T00:55:50.703Z","recordingUrl":"/api/v1/conversation-items/VMn_5L1iTPmcM5DBP1U8oQ/media/recording","recordingStatus":"AVAILABLE","recordingDuration":13,"type":"VOICEMAIL"}} {"id": "SShWgSCHSHy6EO5TiL7rNw","conversationId": "gHuxLQNXSAmmWuNePSyVTw","customerId": "0EphnSIJR0ycjMWFTf-GXA","timestamp": "2020-04-20T23:58:51.941Z","initiator": {"type":"AGENT","id":"LsFXSnO6Ty6gdnyH6y8yug"},"content":{"type":"CONVERSATION_STATUS_CHANGE","status":"CLOSED"}} {"id": "DnaU23pZSIqOixATlII1vA","conversationId": "HXRqKC5GSV-jAlq0-sxYTA","customerId": "o2sg-TMTSD2rTwMuxzewbA","timestamp": "2020-04-24T23:42:57.780Z","initiator": {"type":"AGENT","id":"zGaHXjD4SR-moMR9LbULDA"},"content":{"type":"CONVERSATION_NOTE","body":"Customer has requested more information about our loyalty program."}} ``` **customers.jsonl** ``` {"id": "OOrlNMXeS72gs_WEX2TtMg","name": "Martha J Williams","address": "563 Rigoberto Station Apt. 197","emailAddresses": ["Martha.Williams@gmail.com"],"phoneNumbers": ["+17244895501"],"externalCustomerId": "a21c1636-c622-48b7-bf6a-d9032645aa55"} ``` **topics.jsonl** ``` {"id": "uu4t00vITaKQ3bVjU2UrGQ","name": "Order Returns","disabled": false} ``` Parameters: - jobId [path]: string (required) - id of the job - filename [path]: string (required) - name of the file Responses: 200: returns a file One of: 404: file not found --- ## POST /api/v1/campaigns/{campaignId}/recipient-collections Tags: Proactive Conversations Summary: Create recipient collection for an existing proactive campaign Operation ID: createRecipientCollection 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. Parameters: - campaignId [path]: string (required) - id of the campaign to create a new recipient collection for Request Body: Content-Type: application/json Responses: 200: created recipient collection 404: campaign not found --- ## POST /api/v1/reports Tags: Reports Summary: Generate a report 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. Request Body: Parameters describing the report to generate. Content-Type: application/json Responses: 200: Report CSV 400: Invalid request --- ## GET /api/v1/webhooks Tags: Webhooks Summary: List webhooks Operation ID: getWebhooks Returns a list of webhooks. Responses: 200: Webhook --- ## POST /api/v1/webhooks Tags: Webhooks Summary: Create webhook Operation ID: createWebhook 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. Request Body: Webhook to add Content-Type: application/json Responses: 201: Created webhook 400: Invalid field(s) in request body --- ## GET /api/v1/webhooks/{webhookId} Tags: Webhooks Summary: Get webhook Operation ID: getWebhook Get a webhook by ID Parameters: - webhookId [path]: string (required) - id of the webhook Responses: 200: Webhook 404: Webhook with id does not exist --- ## PATCH /api/v1/webhooks/{webhookId} Tags: Webhooks Summary: Update webhook Operation ID: updateWebhook 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). Parameters: - webhookId [path]: string (required) - id of the webhook Request Body: JSON patch of webhook properties to insert or update Content-Type: application/json Responses: 204: Updated webhook 400: Invalid field(s) in request body 404: Webhook with id does not exist --- ## DELETE /api/v1/webhooks/{webhookId} Tags: Webhooks Summary: Delete webhook Operation ID: deleteWebhook Delete a webhook by ID Parameters: - webhookId [path]: string (required) - id of the webhook Responses: 204: Webhook deleted 400: Webhook must be disabled to be deleted 404: Webhook with id does not exist --- ## POST /gladly/webhook Tags: Payloads Operation ID: Events 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. Request Body: the event payload Content-Type: application/json Responses: 200: Success --- ## POST /api/v1/reports/work-session-events Tags: Reports Summary: Generate a work session report > **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. > To generate a Work Sessions V4 Report, use the [Reports API](/rest/#tag/Reports). A **Work Session** represents a period of time that an Agent spends working with a Customer on a given channel, during a given Contact (messaging exchange, phone call, etc.). In particular: - A Customer may have 0 or more Conversations, but only 1 Conversation is open at any given time. - A Conversation may contain 0 or more Contacts (e.g.: A single phone call, a chat session, an email session). - A Contact may have 0 or more Work Sessions (i.e.: Agents who work on the Contact). - A Work Session is the unique combination of contact_session_id and agent_id. The agent_id column will be NULL if the contact has not been handled by any Agent. The Work Session Report API contains **both** contacts and work sessions. It allows you to understand what your inbound contact volume looks like, and to get a view into how Agents are using their time. The primary use of this information is for forecasting and scheduling purposes, but it can also be used to understand, at a fine-grained level, aspects of agent behavior, agent performance, multichannel conversation patterns and more. The time anchor for data returned by this API is COALESCE(contact_session_created_at, contact_session_ended_at) (i.e.: if contact_session_ended_at does not exist, use contact_session_created_at. Otherwise, use contact_session_ended_at). This means that if it is currently 2023-03-23T00:00Z and: - contact_session_id A was created on 2023-03-21T04:00Z and ended on 2023-03-22T04:00Z - You set the startAt time filter to 2023-03-21T00:00Z - You set the endAt time filter to 2023-03-22T00:00Z - You would not be able to retrieve contact_session_id A in your API request. Instead, you will need to set the endAt time filter to now() (aka 2023-03-23T00:00Z) to retrieve the contact information. Therefore, the general recommendation to get correct data is always to set the endAt time to now() rather than the end interval you'd like to analyze - this will accomodate contacts that "move" intervals due to ending. Note that: - work_session_unknown_time_sec and work_session_after_contact_time_sec may accumulate after the contact ends and before the conversation ends / another contact begins - work_session_handle_time_sec will only be available for a contact after it ends - This report is subject to the same [data latency](https://help.gladly.com/docs/why-is-my-reporting-data-not-current) as other Gladly reports This CSV file contains the following columns, whose definitions may be viewed via the [Work Sessions](https://help.gladly.com/docs/work-sessions) section of the help docs. - id - contact_session_id - contact_session_created_at - customer_id - conversation_id - inbox_id - channel - direction - agent_accepted_at - contact_session_routed_at - agent_id - sla_fulfilled_at - contact_session_ended_at - status - within_sla - work_session_handle_time_sec - work_session_after_contact_time_sec - work_session_unknown_time_sec - accepted_inbox_id Request Body: A time range for the report that will be generated. Content-Type: application/json Responses: 200: Work Session Report CSV 400: Bad Request --- ## GET /api/v1/events Tags: Events Summary: List events Returns a stream of events for the specified entities within the given time range. Responses are streamed using JSONL. Events are up to 15 seconds behind real-time. ``` /api/v1/events?startAt=2020-05-20T14:00:00Z&entities=AGENT_STATUS&entities=AGENT_AVAILABILITY ``` Parameters: - startAt [query]: string (required) - 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. - endAt [query]: string - 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. - entities [query]: array (required) - Entity types that have associated events. Any number of types is acceptable and at least one must be present Responses: 200: Events Streaming Response 400: Bad Request --- ## GET /api/v1/endpoints Tags: Endpoints Summary: List Endpoints Operation ID: getEndpoints Returns a list of all endpoints configured for your organization. Responses: 200: Endpoints --- ## GET /api/v1/endpoints/{endpointId} Tags: Endpoints Summary: Get Endpoint Operation ID: getEndpoint Get a single endpoint by its unique id. Parameters: - endpointId [path]: string (required) - id of the endpoint Responses: 200: Endpoint 400: No endpoint with the given id exists ---