Gladly API (1.0)
Download OpenAPI specification:Download
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.
You can integrate easily with Gladly by calling Gladly's REST API and implementing the 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.
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.
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.
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.
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. With these permissions, you can then go on to create the API Token(s) you need to access Gladly's API resources.
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 below.
To allow a user to create API tokens and access the API:
- Log in to your Gladly instance.
- Open the menu on the top left-hand corner of the page.
- Navigate to Settings > *Users
- Search and click the user profile you wish to give access to.
- You'll see a permission called API User. Select it, while making sure to keep the user's Agent role intact.
- 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.
You must create an API token to access Gladly API resources (see above 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.
Should you lose this token, or wish to rotate your application keys, you can do the following:
- Generate a new token.
- Store the new token in a secure location.
- Delete the old token.
- Update your applications/scripts with the new token.
BasicAuth
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.
curl -u user@organization.com:$GLADLY_API_TOKEN \
https://organization.gladly.com/api/v1/organization| Security Scheme Type | HTTP |
|---|---|
| HTTP Authorization Scheme | basic |
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.
Get Agent
Get an agent profile by their unique id.
path Parameters
| agentId required | string Example: WmeA3Y51Q5ayCAaZ1AotIA id of the agent |
Responses
Agent
Response samples
- 200
{- "id": "WmeA3Y51Q5ayCAaZ1AotIA",
- "name": "Amy Agent",
- "emailAddress": "amy.agent@company.com"
}Get Agent CallRecorder
Get an agent call recording status.
path Parameters
| agentId required | string Example: WmeA3Y51Q5ayCAaZ1AotIA OR agent@customer.com Gladly ID or Gladly email address of the agent |
Responses
CallRecorder
Agent not found
Response samples
- 200
- 404
{- "agentId": "WmeA3Y51Q5ayCAaZ1AotIA",
- "customerId": "ZcyobierQhucTS5GV1R2Fw",
- "conversationItemId": "g6UatsvAQC69AcDpOKF-yQ",
- "recording": "true"
}Update Agent CallRecorder
Update an agent's active call recording status. This API allows changing the recording property.
path Parameters
| agentId required | string Example: WmeA3Y51Q5ayCAaZ1AotIA OR agent@customer.com Gladly ID or Gladly email address of the agent |
Request Body schema: application/json
JSON patch of CallRecorder
| agentId | string Id of the agent |
| customerId | string 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 |
| conversationItemId | string 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 |
| recording | boolean If the call is currently being recorded or not |
Responses
Call recording updated. If an agent is not on a call the update will do nothing.
Agent not found
Request samples
- Payload
{- "recording": false
}Response samples
- 404
{- "errors": {
- "code": "not_exist",
- "detail": "agent WmeA3Y51Q5ayCAaZ1AotIA does not exist"
}
}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 Glad App web widget, use to build your website's help center/FAQ page, or publish on any page on your website.
This API can be used without an API token because it only provides access to public content. You may also work with Gladly Support to enable CORS access so the API can be used directly from client-side javascript.
How a user creates a public answer in Gladly
How that answer is searched and displayed on the Glad App Web widget
Search public answers
Returns a list of answers that match the provided query string.
path Parameters
| orgId required | string Example: ihKsWxiZCDVtXg1iwVmT9Q id of your organization You can look up the ID using the Get organization API. |
query Parameters
| q | string Example: q=reset%20password search term |
| lng | string Example: lng=en-us language code |
| audienceId | string Example: audienceId=en-us 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
found answers
Response samples
- 200
[- {
- "id": "1grfSzATQLa334VDLCWc4A",
- "name": "How to reset your password"
}
]List public answers
Returns the first 1000 public answers sorted alphabetically by name.
path Parameters
| orgId required | string Example: ihKsWxiZCDVtXg1iwVmT9Q id of your organization You can look up the ID using the Get organization API. |
query Parameters
| lng | string Example: lng=es-419 Language of the answers returned Defaults to |
| audienceId | string Example: audienceId=ihKsWxiZCDVtXg1iwVmT9Q 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
answers
Response samples
- 200
[- {
- "id": "1grfSzATQLa334VDLCWc4A",
- "name": "How to reset your password",
- "bodyHtml": "<div><a href=\"/reset-password\">Click here</a> to reset your password</div>",
- "language": "en-us",
- "updatedAt": "2023-05-22T10:00:00.000Z"
}
]List Help Center Answer Titles
Returns an array of answers configured in Help Center sections with their ID and name
path Parameters
| orgId required | string Example: ihKsWxiZCDVtXg1iwVmT9Q id of your organization You can look up the ID using the Get organization API. |
| helpCenterId required | string Example: ihKsWxiZCDVtXg1iwVmT9Q 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 |
query Parameters
| lng | string Example: lng=es-419 Language of the answers returned Defaults to |
| audienceId | string Example: audienceId=ihKsWxiZCDVtXg1iwVmT9Q 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
answers
Response samples
- 200
[- {
- "id": "1grfSzATQLa334VDLCWc4A",
- "name": "How to reset your password"
}
]Get public answer
Returns the answer with the provided id.
path Parameters
| orgId required | string Example: ihKsWxiZCDVtXg1iwVmT9Q id of your organization You can look up the ID using the Get organization API. |
| answerId required | string Example: 1grfSzATQLa334VDLCWc4A id of the answer |
query Parameters
| lng | string Example: lng=en-us language code |
Responses
answer
Response samples
- 200
{- "id": "1grfSzATQLa334VDLCWc4A",
- "name": "How to reset your password",
- "bodyHtml": "<div><a href=\"/reset-password\">Click here</a> to reset your password</div>",
- "language": "en-us",
- "updatedAt": "2023-05-22T10:00:00.000Z"
}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)
Add answer
Adds an answer to the list of answers.
Request Body schema: application/json
| id | string unique answer id - optional (a new id will be generated if not provided) |
| name | string Customer facing answer name |
| description | string 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 |
| audienceIds | Array of strings List of Audience IDs to be associated with the answer |
Responses
Added answer
Bad Request
Specified id is in use
Request samples
- Payload
{- "name": "How to reset your password",
- "description": "This is my first answer",
- "audienceIds": [
- "audience-1",
- "audience-2"
]
}Response samples
- 200
- 400
- 409
{- "id": "1grfSzATQLa334VDLCWc4A",
- "name": "How to reset your password",
- "description": "This is my first answer",
- "audienceIds": [
- "audience-1",
- "audience-2"
], - "createdAt": "2024-06-13T15:16:29.894Z"
}Get Answer
Returns the answer requested.
path Parameters
| answerId required | string Example: 1grfSzATQLa334VDLCWc4A id of the answer |
Responses
answer
Answer does not exist
Response samples
- 200
- 404
{- "id": "1grfSzATQLa334VDLCWc4A",
- "name": "How to reset your password",
- "description": "This is my first answer",
- "audienceIds": [
- "audience-1",
- "audience-2"
], - "updatedAt": "2024-06-13T15:16:29.894Z",
- "createdAt": "2024-06-13T15:16:29.894Z"
}Update Answer
Updates the answer with the provided id.
path Parameters
| answerId required | string Example: 1grfSzATQLa334VDLCWc4A id of the answer |
Request Body schema: application/json
| name | string Customer facing answer name |
| description | string 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 |
| audienceIds | Array of strings 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. |
Responses
Answer updated
Bad Request
Answer does not exist
Request samples
- Payload
{- "name": "How to reset your password",
- "description": "This is my first answer",
- "audienceIds": [
- "audience-1",
- "audience-2"
]
}Response samples
- 400
- 404
{- "errors": [
- {
- "attr": "name",
- "code": "taken",
- "detail": "duplicate answer name"
}
]
}Delete Answer
Deletes the answer with the provided id.
path Parameters
| answerId required | string Example: 1grfSzATQLa334VDLCWc4A id of the answer |
Responses
Answer deleted
Bad Request
Answer does not exist
Response samples
- 400
- 404
{- "errors": [
- {
- "attr": "answer",
- "code": "in_use",
- "detail": "answer is associated with rules"
}
]
}Get Answer Content
Returns the answer content requested by language and type.
path Parameters
| answerId required | string Example: 1grfSzATQLa334VDLCWc4A id of the answer |
| language required | string Example: en-us Language code according to ISO 639 format. The specified language must also be configured for the org. |
| type required | string Example: public Type of answer. Must be one of |
Responses
answerContent
Bad Request
Answer content does not exist
Response samples
- 200
- 400
- 404
{- "answerId": "1grfSzATQLa334VDLCWc4A",
- "language": "en-us",
- "type": "public",
- "bodyHtml": "<div>Public content</div>",
- "title": "Reset Password"
}Add or Update Answer Content
Adds or Updates the answer content for the specified answer by language and type. Currently, only public content is supported for add or update.
path Parameters
| answerId required | string Example: 1grfSzATQLa334VDLCWc4A id of the answer |
| language required | string Example: en-us Language code according to ISO 639 format. The specified language must also be configured for the org. |
| type required | string Example: public Type of answer. Must be |
Request Body schema: application/json
| bodyHtml | string The body of the answer content |
| title | string Title of the answer content |
Responses
Added/Updated answer content
Bad Request
Answer does not exist
Request samples
- Payload
{- "bodyHtml": "<div>Public content</div>",
- "title": "Reset Password"
}Response samples
- 200
- 400
- 404
{- "answerId": "1grfSzATQLa334VDLCWc4A",
- "language": "en-us",
- "type": "public",
- "bodyHtml": "<div>Public content</div>",
- "title": "Reset Password"
}Delete Answer Content
Deletes the answer content for the specified answer by language and type.
path Parameters
| answerId required | string Example: 1grfSzATQLa334VDLCWc4A id of the answer |
| language required | string Example: en-us Language code according to ISO 639 format. The specified language must also be configured for the org. |
| type required | string Example: public Type of answer. Must be one of |
Responses
Answer content deleted
Bad Request
Does not exist
Response samples
- 400
- 404
{- "errors": [
- {
- "attr": "language",
- "code": "invalid",
- "detail": "invalid language"
}
]
}An Audience represents a brand (or segment) specially for a multi-brand company. They are used to categorize Answers, Help Centers and Glad Apps for the specific brands. The API allows you to lookup the audiences that have been created for the organization.
Communications API enables you to programmatically send SMS messages to your customers and receive messages from a custom channel integration.
Agent View
Consumer View
Send SMS
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 with a P4 designation.
Please be aware that:
- Any automated outbound text messages must comply with carrier acceptable use policies (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 and you pay per segment. We highly recommend using the segment calculator when crafting automated outbound text messages.
- Each type of phone number has a Message Segments per Second limit.
Request Body schema: application/json
SMS to send
| customer required | object (customer with mobile number) |
| from required | string (mobile number) |
| body required | string (SMS message) |
Responses
the customer and conversation item ID
Invalid field(s) in request body
Request samples
- Payload
{- "customer": {
- "mobileNumber": "+14152223000"
}, - "from": "+14152223316",
- "body": "hello, this is a sample SMS message!"
}Response samples
- 200
- 400
{- "customerId": "gHufx-U3QqOmhvFuViceTw",
- "conversationItemId": "pOVVdzweSumI4bFxjlT8LA"
}Receive Custom Channel messages
Custom Channels allows for building custom channel integration with Gladly. This functionality is deactivated by default.
Note that the intended use case for custom channels is any non Gladly messaging-based supported channel, such as a third party chat or SMS service.
Please contact Gladly Support if you would like to activate this API and believe you have a valid use case.
To receive a Custom Channel message, you must first create a Custom Channel and a Custom Channel Entry Point in Gladly Settings -> Custom Channels page. This API will accept messages from the channel integration and process them similarly to built-in messaging channels.
path Parameters
| customChannelId required | string The ID of the Custom Channel. To find the Custom Channel ID, you must open the overflow menu of a Custom Channel Entry Point and select the "View Integration Data" option. |
Request Body schema: application/json
Custom Channel message
| sender required | object |
| to required | string Unique identifier of the recipient Channel. This should correspond to the Entry Point "Address" field created for the Custom Channel in Gladly. |
| type required | string Enum: "TEXT" "FILES" Describes the message type |
| groupId | string (Message Group ID) Optional message group ID that can be associated with a message, the Custom Channel must be configured for Message Groups in order to use this field. |
| groupName | string (Message Group Name) Used together with |
| content required | Plain text message (object) or Files message (object) |
Responses
Message received
Invalid fields(s) in the request body
Request samples
- Payload
{- "sender": {
- "address": "string",
- "displayName": "string",
- "profileIdentifier": {
- "type": "EMAIL",
- "address": "string"
}
}, - "to": "string",
- "type": "TEXT",
- "groupId": "string",
- "groupName": "string",
- "content": {
- "text": "string"
}
}Response samples
- 400
{- "errors": [
- {
- "attr": "content",
- "code": "blank",
- "detail": "content cannot be blank"
}
]
}Update message status
Update message status of Custom Channel messages sent from agents. This allow a Custom Channel integration to set message status to indicate to an Agent that the message has been delivered.
path Parameters
| customChannelId required | string The ID of the Custom Channel. To find the Custom Channel ID, you must open the overflow menu of a Custom Channel Entry Point and select the "View Integration Data" option. |
| messageId required | string The id of message updated |
Request Body schema: application/json
Custom Channel message status
| value required | string Enum: "ACCEPTED" "DELIVERED" "READ" "FAILED" |
| details | string Optional status details. It is particularly useful when the value is 'Failed'. |
Responses
Status updated
Invalid fields(s) in the request body
Message with messageId not found
Request samples
- Payload
{- "value": "ACCEPTED",
- "details": "string"
}Response samples
- 400
- 404
{- "errors": [
- {
- "attr": "content",
- "code": "blank",
- "detail": "content cannot be blank"
}
]
}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.
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 channel | Yes | Yes | No | No | No |
| Conversation Status Change | Conversation status changed (e.g.: from OPEN to WAITING, or OPEN to CLOSED) | Yes | Yes | Yes | No | No |
| Custom Channel Message | A Message sent/received via a Custom Channel integration | No | Yes | No | No | No |
| Customer Activity | Non-routable customer activity added to customer timeline via API | Yes | Yes | No | Yes | No |
| A message sent/received via the Email channel | Yes | Yes | No | No | No | |
| Facebook Messenger Message | A message sent/received via the Facebook Messenger channel | Yes | Yes | No | No | No |
| Instagram Direct | A message sent/received via the Instagram channel | No | Yes | No | No | No |
| Note | An internal Note on the Customer conversation | Yes | Yes | No | No | No |
| Phone Call | A Phone Call placed/received on Gladly | No | Yes | No | No | Yes |
| SMS Message | A message sent/received via the SMS channel | Yes | Yes | No | No | No |
| Task | A Task on a Customer's profile | Yes | Yes | Yes | No | No |
| Topic Change | A Topic 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 channel | No | Yes | No | Yes | No |
| Voicemail | A Voicemail received | No | Yes | No | No | Yes |
| 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.
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.
Task
Interacting with tasks through the conversations API is deprecated. Use Tasks API instead.
Topic Change
Record of an agent adding or removing a topic from a conversation in Gladly.
Twitter (decommissioned as of 04/20/23)
Content of messages sent between Gladly and customers on Twitter.
Voicemail
Information about voicemail left by customers in Gladly.
Content of messages sent between Gladly and customers on WhatsApp.
Get conversations for customer
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.
path Parameters
| customerId required | string Example: gHufx-U3QqOmhvFuViceTw Id of the customer to get all conversations for |
Responses
The conversations for the customer
Response samples
- 200
[- {
- "id": "HXRqKC5GSV-jAlq0-sxYTA",
- "topicIds": [
- "_DZTz4I0Qsq9YXxeXwufMg",
- "tYVmwhIVQe-2tflRIszQ3g"
], - "customAttributes": [
- {
- "id": "UCeBpdBVSNyaP54jhd8CZw",
- "value": "1234556777"
}, - {
- "id": "UCeBpdBVSNyaP54jhd8CZw",
- "value": "883399334403"
}, - {
- "id": "cEBkE90eQHObfcsnrm60Tg",
- "value": "UPS"
}
], - "customerId": "o2sg-TMTSD2rTwMuxzewbA",
- "createdAt": "2016-01-02T00:10:00Z",
- "agentId": "sHuXx-U3QqOmhvFusJGeBw",
- "inboxId": "E1nArq1uQAees_DogHB0MA",
- "status": "OPEN"
}, - {
- "id": "UMTZxwzJRyejwOj4NDfjeg",
- "topicIds": [
- "tYVmwhIVQe-2tflRIszQ3g"
], - "customAttributes": [
- {
- "id": "UCeBpdBVSNyaP54jhd8CZw",
- "value": "1234556777"
}, - {
- "id": "UCeBpdBVSNyaP54jhd8CZw",
- "value": "883399334403"
}, - {
- "id": "cEBkE90eQHObfcsnrm60Tg",
- "value": "UPS"
}
], - "customerId": "o2sg-TMTSD2rTwMuxzewbA",
- "createdAt": "2016-01-02T00:10:00Z",
- "closedAt": "2016-01-03T08:10:00Z",
- "agentId": "sHuXx-U3QqOmhvFusJGeBw",
- "inboxId": "E1nArq1uQAees_DogHB0MA",
- "status": "CLOSED"
}
]Get conversation
Get conversation metadata such as it's assignee, topics, inbox, etc.
path Parameters
| conversationId required | string Example: 9BcE2O0DQ2ynGHRmk9FeoA Id of the conversation to get |
Responses
Conversation metadata
A conversation with the given id does not exist
Response samples
- 200
{- "id": "HXRqKC5GSV-jAlq0-sxYTA",
- "topicIds": [
- "_DZTz4I0Qsq9YXxeXwufMg",
- "tYVmwhIVQe-2tflRIszQ3g"
], - "customAttributes": [
- {
- "id": "UCeBpdBVSNyaP54jhd8CZw",
- "value": "1234556777"
}, - {
- "id": "UCeBpdBVSNyaP54jhd8CZw",
- "value": "883399334403"
}, - {
- "id": "cEBkE90eQHObfcsnrm60Tg",
- "value": "UPS"
}
], - "customerId": "o2sg-TMTSD2rTwMuxzewbA",
- "createdAt": "2016-01-02T00:10:00Z",
- "closedAt": "2016-01-03T08:10:00Z",
- "agentId": "sHuXx-U3QqOmhvFusJGeBw",
- "inboxId": "E1nArq1uQAees_DogHB0MA",
- "status": "CLOSED"
}Update conversation
Update conversation assignee, statusor both
path Parameters
| conversationId required | string Example: 9BcE2O0DQ2ynGHRmk9FeoA Id of the conversation |
Request Body schema: application/json
JSON representation of conversation updates
| assignee | object (Assignee Update) |
| status | object (Conversation Status) |
Responses
updated conversation
Invalid request
A conversation with the given id does not exist
Request samples
- Payload
{- "assignee": {
- "inboxId": "E1nArq1uQAees_DogHB0MA",
- "agentId": "sHuXx-U3QqOmhvFusJGeBw"
}, - "status": {
- "value": "CLOSED",
- "force": true
}
}Response samples
- 400
- 404
{- "errors": [
- {
- "attr": "assignee.inboxId",
- "code": "blank",
- "detail": "'inboxId' cannot be blank when updating assignee"
}, - {
- "attr": "status.value",
- "code": "blank",
- "detail": "'value' cannot be blank when updating status"
}
]
}Create item
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 schema: application/json
Conversation Item to create
| id | string <= 50 characters Unique conversation item id. Must be URL safe and under 50 characters. An id will be automatically generated if one is not included. |
| customer required | object (Customer Specification) Specifies the customer an item belongs to. You must provide exactly one of the values. |
| content required | Customer Activity (object) or Task (deprecated) (object) (Conversation Item Content To Create) |
Responses
The created item
Invalid field(s) in request body
Specified id is in use
Request samples
- Payload
{- "id": "pOVVdzweSumI4bFxjlT8LA",
- "customer": {
- "emailAddress": "michelle.smith@example.org"
}, - "content": {
- "type": "CUSTOMER_ACTIVITY",
- "title": "Welcome to Gladly!",
- "body": "At Gladly we set out to reinvent customer service. Why? Because 21st century consumers are different. They are from 18 to 80 years old, expect the brands they love to recognize them, and to be able to communicate with your agents over all channels – all the time.",
- "activityType": "EMAIL",
- "sourceName": "HubSpot",
}
}Response samples
- 200
- 400
- 409
{- "id": "pOVVdzweSumI4bFxjlT8LA",
- "customerId": "gHufx-U3QqOmhvFuViceTw",
- "timestamp": "2019-07-03T04:30:12.07Z",
- "initiator": {
- "id": "gHufx-U3QqOmhvFuViceTw",
- "type": "CUSTOMER"
}, - "responder": {
- "id": "zGaHXjD4SR-moMR9LbULDa",
- "type": "AGENT"
}, - "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",
- "expandByDefault": true,
- "occurredAt": "2016-04-11T14:09:23.000Z",
- "receivedAt": "2019-01-11T20:49:55.000Z"
}
}Get item
Returns the conversation item with the provided id.
path Parameters
| itemId required | string Example: pOVVdzweSumI4bFxjlT8LA id of the conversation item |
Responses
conversation item
An item exists but is not supported by the API
An item with the given id could not be found
Response samples
- 200
- 400
{- "id": "pOVVdzweSumI4bFxjlT8LA",
- "customerId": "gHufx-U3QqOmhvFuViceTw",
- "conversationId": "PmDVUfWfRjKuwb4VgA2zEA",
- "timestamp": "2019-07-03T04:30:12.07Z",
- "initiator": {
- "id": "gHufx-U3QqOmhvFuViceTw",
- "type": "CUSTOMER"
}, - "responder": {
- "id": "zGaHXjD4SR-moMR9LbULDa",
- "type": "AGENT"
}, - "content": {
- "type": "CHAT_MESSAGE",
- "messageType": "TEXT",
- "sessionId": "5k04bYuTRGqyT6uoSQfWVA",
- "content": "HI! Can you help me with my order?"
}
}Delete item
To delete an item.
Please note only items of type CUSTOMER_ACTIVITY may be deleted by this API.
path Parameters
| itemId required | string Id of the item to be deleted. |
Responses
The item was deleted
An item with the given id could not be found
Get media
Returns the media file associated with the conversation item
path Parameters
| itemId required | string Example: pOVVdzweSumI4bFxjlT8LA id of the conversation item |
Responses
The media file associated with the conversation item
An item with the given id could not be found
Get voice transcript
Returns a transcript of a phone call or a voicemail
path Parameters
| itemId required | string Example: pOVVdzweSumI4bFxjlT8LA id of the conversation item |
Responses
The voice transcript of a phone call or a voicemail
A transcript with the given id could not be found
Response samples
- 200
{- "paragraphs": [
- {
- "transcript": "Hello! How are you doing today?",
- "speaker": 0,
- "startTime": 2.48,
- "endTime": 6.1
}
], - "customerId": "AloLvEkzQlqc7c4kyYQY1A",
- "numberOfSpeakers": 1,
- "language": "string",
- "createdAt": "2024-05-15T14:09:23.000Z",
- "updatedAt": "2024-05-15T14:19:23.000Z"
}Create item for customer
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.
path Parameters
| customerId required | string Id of the customer associated with this item. You can look up the id using the Find customers API. |
Request Body schema: application/json
Conversation Item to create
| id | string <= 50 characters Unique conversation item id. Must be URL safe and under 50 characters. An id will be automatically generated if one is not included. |
| content required | Customer Activity (object) or Task (deprecated) (object) (Conversation Item Content To Create) |
Responses
The created item
This customer id no longer exists, but has been moved because it has been merged with another customer
Invalid field(s) in request body
Customer with customerId does not exist
Specified id is in use
Request samples
- Payload
{- "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",
}
}Response samples
- 200
- 301
- 400
- 409
{- "id": "pOVVdzweSumI4bFxjlT8LA",
- "customerId": "gHufx-U3QqOmhvFuViceTw",
- "timestamp": "2019-07-03T04:30:12.07Z",
- "initiator": {
- "id": "gHufx-U3QqOmhvFuViceTw",
- "type": "CUSTOMER"
}, - "responder": {
- "id": "zGaHXjD4SR-moMR9LbULDa",
- "type": "AGENT"
}, - "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",
- "expandByDefault": true,
- "occurredAt": "2016-04-11T14:09:23.000Z",
- "receivedAt": "2019-01-11T20:49:55.000Z"
}
}Delete item for customer
To delete an item.
Please note only items of type CUSTOMER_ACTIVITY may be deleted by this API.
path Parameters
| customerId required | string Id of the customer associated with this item. You can look up the id using the Find customers API. |
| itemId required | string Id of the item to be deleted. |
Responses
The item was deleted
An item with the given id, for the given customer id, could not be found
List items in conversation
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.
path Parameters
| conversationId required | string Example: 9BcE2O0DQ2ynGHRmk9FeoA Id of the conversation to get the timeline for |
Responses
The items on the conversation timeline
A conversation with the given id does not exist
Response samples
- 200
[- {
- "id": "ybP4szYCSy6LdV4DNwEd6g",
- "conversationId": "9BcE2O0DQ2ynGHRmk9FeoA",
- "customerId": "OOrlNMXeS72gs_WEX2TtMg",
- "timestamp": "2019-07-01T11:46:45.01Z",
- "initiator": {
- "id": "OOrlNMXeS72gs_WEX2TtMg",
- "type": "CUSTOMER"
}, - "content": {
- "type": "CHAT_MESSAGE",
- "sessionId": "5k04bYuTRGqyT6uoSQfWVA",
- "content": "Hi! I know it's after hours but can someone help upgrade my account?"
}
}, - {
- "id": "9lQDrx-HTz-JMoP2T4CtZA",
- "conversationId": "9BcE2O0DQ2ynGHRmk9FeoA",
- "customerId": "OOrlNMXeS72gs_WEX2TtMg",
- "timestamp": "2019-07-02T06:30:12.07Z",
- "initiator": {
- "id": "WmeA3Y51Q5ayCAaZ1AotIA",
- "type": "AGENT"
}, - "content": {
- "type": "EMAIL",
- "from": "amy.agent@company.com",
- "to": [
- "martha.williams@gmail.com"
], - "subject": "Account upgrade",
- "content": "I would be happy to help you! We need a few details, so please give us a call this morning."
}
}, - {
- "id": "S6pMkJ78QMmkVf9qPP_SeQ",
- "conversationId": "9BcE2O0DQ2ynGHRmk9FeoA",
- "customerId": "OOrlNMXeS72gs_WEX2TtMg",
- "timestamp": "2019-07-02T08:05:00.10Z",
- "initiator": {
- "id": "OOrlNMXeS72gs_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": "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."
}
}
]Add Topics to Conversation
Adds a list of topics to the conversation. If a topic being added already exists on the conversation, that topic is ignored.
path Parameters
| conversationId required | string Id of the conversation. |
Request Body schema: application/json
| topicIds | Array of strings Topic Ids to be added to the conversation. |
Responses
The topic was added successfully
Invalid field(s) in request body
A conversation with the given Id could not be found
Request samples
- Payload
{- "topicIds": [
- "pOVVdzweSumI4bFxjlT8LA",
- "pOVVdzweSumI4bFxjlT8LB"
]
}Response samples
- 400
{- "errors": [
- {
- "attr": "content",
- "code": "blank",
- "detail": "content cannot be blank"
}
]
}Delete Topic from Conversation
Delete a topic from a conversation.
path Parameters
| conversationId required | string Id of the conversation. |
| topicId required | string Id of topic to be deleted from conversation. |
Responses
The topic was deleted from the conversation successfully
A conversation with the given id could not be found
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.
path Parameters
| customerId required | string Id of the customer. |
| conversationId required | string Id of the conversation. |
Request Body schema: application/json
| body | string Freeform topics that need to be added or removed from a conversation |
Responses
The freeform topic was added successfully
Invalid field(s) in request body
A conversation with the given Id could not be found
Request samples
- Payload
{- "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"
}
]
}Response samples
- 400
{- "errors": [
- {
- "code": "not_exist",
- "detail": "entity does not exist"
}
]
}Add note
Adds note to an existing conversation.
path Parameters
| conversationId required | string Id of the conversation. |
Request Body schema: application/json
| body | string Plain text or rich content of the note. |
Responses
The note was added successfully
Invalid field(s) in request body
A conversation with the given Id could not be found
Request samples
- Payload
{- "content": {
- "body": "Customer has requested more information about our loyalty program."
}
}Response samples
- 400
{- "errors": [
- {
- "attr": "content",
- "code": "blank",
- "detail": "content cannot be blank"
}
]
}Get note
Returns the note with the provided conversation and note id.
path Parameters
| conversationId required | string Example: pOVVdzweSumI4bFxjlT8LA id of the conversation |
| noteId required | string Example: aOVVdzweSumI4bFxjlT8LA id of the note |
Responses
Conversation note
An item with the given id could not be found
Response samples
- 200
{- "id": "pOVVdzweSumI4bFxjlT8LA",
- "customerId": "gHufx-U3QqOmhvFuViceTw",
- "conversationId": "PmDVUfWfRjKuwb4VgA2zEA",
- "timestamp": "2019-07-03T04:30:12.07Z",
- "initiator": {
- "id": "gHufx-U3QqOmhvFuViceTw",
- "type": "CUSTOMER"
}, - "responder": {
- "id": "zGaHXjD4SR-moMR9LbULDa",
- "type": "AGENT"
}, - "content": {
- "type": "CONVERSATION_NOTE",
- "body": "Customer has requested more information about our loyalty program."
}
}Reply to message
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.
path Parameters
| itemId required | string Example: pOVVdzweSumI4bFxjlT8LA id of the conversation item |
Request Body schema: application/json
| content required | Email Message Content (object) or (Chat Message Content (Message Content (object) or QuickReply Request Content (object))) or Facebook Message Content (object) or Instagram Direct Message Content (object) or SMS Message Content (object) or Twitter Direct Message Content (decommissioned as of 04/20/2023) (object) or WhatsApp Message Content (object) (Message content) |
Responses
The reply was created successfully. Note that creation doesn't guarantee delivery
Invalid field(s) in request body
A conversation item with the given id could not be found
Request samples
- Payload
{- "content": {
- "type": "EMAIL",
- "body": "<h>Hi!</h><br>Of course we can help with your issue!",
- "bodyPlain": "Hi!\n We can definitely help you with that!"
}
}Response samples
- 400
{- "errors": [
- {
- "code": "invalid",
- "detail": "you cannot reply to items in closed conversations"
}
]
}Redact conversation item
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.
path Parameters
| itemId required | string Example: pOVVdzweSumI4bFxjlT8LA id of the conversation item |
Request Body schema: application/json
The request body should be empty
Responses
The redaction was successful.
A conversation item with the given id could not be found
Request samples
- Payload
nullA 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.
Create customer
Create a new customer with the supplied profile data.
Request Body schema: application/json
Customer record to add.
| name | string Customer's name |
| image | string URL for an image that will appear as the customer's avatar |
| address | string Customer's street address |
| emails | Array of objects (email addresses) Customer's email addresses |
| phones | Array of objects (phone numbers) Customer's phone numbers |
| externalCustomerId | 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 will not exist and cannot be set. |
| customAttributes | object 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. |
| id | string Unique customer id. Must be URL safe and under 50 characters. An id will be automatically generated if one is not included |
Responses
customer created
error creating customer
Specified id is in use or a uniqueness constraint failed
Request samples
- Payload
{- "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"
}
}Response samples
- 400
- 409
{- "errors": [
- {
- "attr": "content",
- "code": "blank",
- "detail": "content cannot be blank"
}
]
}Find customers
Find customers by searching by choosing one of the following identifiers as query parameters:
/api/v1/customer-profiles?phoneNumber=%2B14151234567Max limit of 50 profiles returned, sorted by most recently updatedAt date descending.
query Parameters
string Example: email=customer@email.net customer email address to search on. | |
| externalCustomerId | string Example: externalCustomerId=a21c1636-c622-48b7-bf6a-d9032645aa55 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 | string Example: phoneNumber=+16505551987 Phone number in E.164 format. The value should be URL escaped where |
Responses
found customers
error finding customers
Response samples
- 200
- 400
[- {
- "name": "Martha J Williams",
- "address": "563 Rigoberto Station Apt. 197",
- "emails": [
- {
- "normalized": "martha.williams@gmail.com",
- "original": "Martha.Williams@gmail.com",
- "primary": false
}
], - "phones": [
- {
- "normalized": "+17244895501",
- "extension": "123",
- "original": "7244895501",
- "regionCode": "US",
- "primary": false,
- "smsPreference": "OFF",
- "type": "OFFICE"
}
], - "externalCustomerId": "a21c1636-c622-48b7-bf6a-d9032645aa55",
- "customAttributes": {
- "membershipNumber": "RQ564555333",
- "membershipTier": "gold"
}, - "id": "OOrlNMXeS72gs_WEX2TtMg",
- "createdAt": "2019-02-21T07:15:18.07272933Z",
- "updatedAt": "2019-02-21T19:50:23.486566336Z",
- "externalCustomerIds": {
- "ABC12345": "54321"
}
}
]
Get customer
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.
path Parameters
| customerId required | string Example: OOrlNMXeS72gs_WEX2TtMg id of the customer |
Responses
fetched customer
customer id no longer exists and has been changed due to a merge with another customer
customer not found
Response samples
- 200
- 301
- 404
{- "name": "Martha J Williams",
- "address": "563 Rigoberto Station Apt. 197",
- "emails": [
- {
- "normalized": "martha.williams@gmail.com",
- "original": "Martha.Williams@gmail.com",
- "primary": false
}
], - "phones": [
- {
- "normalized": "+17244895501",
- "extension": "123",
- "original": "7244895501",
- "regionCode": "US",
- "primary": false,
- "smsPreference": "OFF",
- "type": "OFFICE"
}
], - "externalCustomerId": "a21c1636-c622-48b7-bf6a-d9032645aa55",
- "customAttributes": {
- "membershipNumber": "RQ564555333",
- "membershipTier": "gold"
}, - "id": "OOrlNMXeS72gs_WEX2TtMg",
- "createdAt": "2019-02-21T07:15:18.07272933Z",
- "updatedAt": "2019-02-21T19:50:23.486566336Z",
- "externalCustomerIds": {
- "ABC12345": "54321"
}
}Update customer
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.
path Parameters
| customerId required | string Example: OOrlNMXeS72gs_WEX2TtMg id of the customer |
Request Body schema: application/json
JSON patch of customer profiles properties to insert or update.
| name | string Customer's name |
| image | string URL for an image that will appear as the customer's avatar |
| address | string Customer's street address |
| emails | Array of objects (email addresses) Customer's email addresses |
| phones | Array of objects (phone numbers) Customer's phone numbers |
| externalCustomerId | 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 will not exist and cannot be set. |
| customAttributes | object 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. |
Responses
updated customer
error updating customer
customer not found
Request samples
- Payload
{- "name": "Frankie Avalon",
- "emails": [
- {
- "original": "existing@francisavallone.com"
}, - {
- "original": "new@frankieavalon.com"
}
], - "customAttributes": {
- "albums": "7",
- "singles": "41"
}
}Response samples
- 400
- 404
{- "errors": [
- {
- "attr": "content",
- "code": "blank",
- "detail": "content cannot be blank"
}
]
}Delete customer
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.
path Parameters
| customerId required | string Example: OOrlNMXeS72gs_WEX2TtMg id of the customer |
Responses
customer was deleted
error deleting customer with open or waiting conversation
Response samples
- 400
{- "errors": {
- "attr": "conversation",
- "code": "invalid_state",
- "detail": "Unable to delete the profile. Please close any open or waiting conversations."
}
}An Event is something that has happened in Gladly. The Events API allows you to extract event details from the past 24 hours.
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_AVAILABILITYquery Parameters
| startAt required | string Example: startAt=2020-04-13T19:27:34-09:00 Starting time of the events interval. This is based on the The date should be in ISO 8601 format. |
| endAt | string Example: endAt=2020-04-13T20:27:12-09:00 Ending time of the events interval. This is based on the The date should be in ISO 8601 format. |
| entities required | array Example: entities=AGENT_AVAILABILITY,AGENT_STATUS Entity types that have associated events. Any number of types is acceptable and at least one must be present Available Types: |
Responses
Events Streaming Response
Bad Request
Response samples
- 200
- 400
{- "id": "zGaHXjD4SR-moMR9LbULDa",
- "type": "AGENT_AVAILABILITY/FOCUS_ENTERED",
- "timestamp": "2019-07-03T04:30:12.07Z",
- "initiator": {
- "id": "NFpDZtfqhk2pI6fjaVDlFf",
- "type": "AGENT"
}, - "content": {
- "agentId": "zGaHXjD4SR-moMR9LbULDa",
- "context": {
- "availableFor": [
- "MAIL",
- "TASK",
- "VOICE"
]
}
}
}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.
List schedules
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
found jobs
Response samples
- 200
[- {
- "id": "vZgCEQlDR6aQz_0HeWZ9_Q",
- "frequency": "HOURLY",
- "type": "CONVERSATIONS",
- "nextStartAt": "2019-01-21T08:00:00.00Z",
- "updatedAt": "2019-01-21T07:15:18.07272933Z"
}
]List jobs
List all jobs for the organization in any status for the last 14 days.
/api/v1/export/jobsYou 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.000Zquery Parameters
| status | string Enum: "PENDING" "IN_PROGRESS" "COMPLETED" "FAILED" Example: status=COMPLETED export job status to search on. |
| startAt | string <ISO 8601> Example: startAt=2024-09-15T00:00:00.000Z Starting time to filter export jobs by. This is based on the The date should be in ISO 8601 format. |
| endAt | string <ISO 8601> Example: endAt=2024-09-16T00:00:00.000Z Ending time to filter export jobs by. This is based on the The date should be in ISO 8601 format. |
Responses
found jobs
Response samples
- 200
[- {
- "id": "vZgCEQlDR6aQz_0HeWZ9_Q",
- "scheduleId": "OOrlNMXeS72gs_WEX2TtMg",
- "status": "COMPLETED",
- "updatedAt": "2019-02-21T07:15:19.07272933Z",
- "parameters": {
- "type": "CONVERSATIONS",
- "startAt": "2019-01-21T07:15:18.07272933Z",
- "endAt": "2019-01-22T07:15:18.07272933Z"
}, - "files": [
- "agents.jsonl",
- "conversation_items.jsonl",
- "customers.jsonl",
- "topics.jsonl"
]
}
]Get job
Get a job by unique id.
path Parameters
| jobId required | string Example: OOrlNMXeS72gs_WEX2TtMg id of the job |
Responses
fetched job
job not found
Response samples
- 200
- 404
{- "id": "vZgCEQlDR6aQz_0HeWZ9_Q",
- "scheduleId": "OOrlNMXeS72gs_WEX2TtMg",
- "status": "COMPLETED",
- "updatedAt": "2019-02-21T07:15:19.07272933Z",
- "parameters": {
- "type": "CONVERSATIONS",
- "startAt": "2019-01-21T07:15:18.07272933Z",
- "endAt": "2019-01-22T07:15:18.07272933Z"
}, - "files": [
- "agents.jsonl",
- "conversation_items.jsonl",
- "customers.jsonl",
- "topics.jsonl"
]
}Delete job
Delete a job and all associated files. Note: job status must be COMPLETED or FAILED to be deleted.
path Parameters
| jobId required | string Example: OOrlNMXeS72gs_WEX2TtMg id of the job |
Responses
the job was deleted
unable to delete job
job not found
Response samples
- 400
- 404
[- {
- "attr": "status",
- "code": "temporary_failure",
- "detail": "unable to delete job with status [IN_PROGRESS]. Please try again after it has finished"
}
]Get file
Download a file generated by a data export job.
Filenames can be found from an export job's 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}path Parameters
| jobId required | string Example: OOrlNMXeS72gs_WEX2TtMg id of the job |
| filename required | string Example: agents.jsonl name of the file |
Responses
returns a file
file not found
Response samples
- 200
- 404
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.
Get custom attribute
Returns a custom attribute that matches the provided custom attribute id.
path Parameters
| customAttributeId required | string Example: 1grfSzATQLa334VDLCWc4A id of the custom attribute |
Responses
Custom Attribute not found
Response samples
- 200
- 404
{- "id": "1grfSzATQLa334VDLCWc4A",
- "key": "orderId",
- "label": "Order ID",
- "deactivated": true,
- "createdAt": "2020-05-20T15:00:00.000Z",
- "createdBy": "7MRwXOeWRaGatwYCbBLLA"
}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.
Get inbox
Get the metadata for an inbox by its unique id.
path Parameters
| inboxId required | string Example: vZgCEQlDR6aQz_0HeWZ9_Q id of the inbox |
Responses
Inbox
Response samples
- 200
{- "id": "vZgCEQlDR6aQz_0HeWZ9_Q",
- "name": "Email Inbox",
- "disabled": false
}The collection of Message Automation APIs are used to facilitate communication between a Customer via a Gladly channel and a 3rd party Automation service, such as a chat bot. These APIs allow an Automation service to interact with a Customer as well as close a Conversation with a Customer or route a Customer to an Agent. Subscribe to the Webhook Event AUTOMATION/MESSAGE_RECEIVED to receive inbound messages.
Get Automation Session
Returns the automation session with the provided sessionId.
path Parameters
| sessionId required | string Example: pOVVdzweSumI4bFxjlT8LA The id of the automation session. |
Responses
Automation Session
An automation session with the given id does not exist.
Response samples
- 200
- 404
{- "id": "hyLceTJzT5yTAxz1SYJ65A",
- "companyAddress": "606b52ba0b806d00d28f841b",
- "conversationId": "wcIVaRWxQKC1PuKYIyruKQ",
- "customerAddress": "x9CubuE1T5q40ULjoFW0iQ",
- "customerId": "qe4WxGejR2miAtCcTAaA4w",
- "endpointType": "CHAT",
- "createdAt": "2022-05-04T06:36:23.944Z",
- "updatedAt": "2022-05-04T06:36:23.944Z",
- "target": {
- "targetType": "AUTOMATION"
}
}Update Typing Indicator State
Update the typing indicator state for the automation session with the provided sessionId.
path Parameters
| sessionId required | string Example: pOVVdzweSumI4bFxjlT8LA Id of the automation session. |
Request Body schema: application/json
Update typing indicator state.
| state required | string Enum: "STARTED" "STOPPED" The state of the typing indicator |
Responses
The typing indicator state is updated.
An automation session with the given id does not exist.
Request samples
- Payload
{- "state": "STARTED"
}Response samples
- 404
{- "errors": [
- {
- "code": "not_exist",
- "detail": "entity does not exist"
}
]
}Send Outbound Automation Message
Create a new outbound automation message for an automation session with the provided sessionId.
path Parameters
| sessionId required | string Example: pOVVdzweSumI4bFxjlT8LA Id of the automation session. |
Request Body schema: application/json
Create an outbound message
| type required | string Enum: "TEXT" "MENU" "HTML" The type of the outbound automation message. |
| content required | Content of Text (object) or Content of Menu (object) or Content of HTML (object) (Outbound Message Content) |
Responses
The outbound automation message is created.
Message has invalid type or content.
Message with the given messageId does not exist in the given automation session.
Request samples
- Payload
{- "type": "TEXT",
- "content": {
- "value": "Your order is on the way!"
}
}Response samples
- 200
- 400
- 404
{- "id": "626c058b82388c00f4770ede",
- "content": {
- "value": "How can I help you?"
}, - "createdAt": "2022-05-04T06:36:23.944Z",
- "from": {
- "type": "CUSTOMER",
- "id": "qe4WxGejR2miAtCcTAaA4w"
}, - "sessionId": "dGwbXv5RR8SjbEln5YlKaQ",
- "type": "TEXT",
}Get Automation Messages
Returns all the messages within the automation session with the provided sessionId.
path Parameters
| sessionId required | string Example: pOVVdzweSumI4bFxjlT8LA Id of the automation session. |
Responses
Automation session messages
An automation session with the given id does not exist
Response samples
- 200
- 404
[- {
- "id": "626c058b82388c00f4770ede",
- "content": {
- "value": "How can I help you?"
}, - "createdAt": "2022-05-04T06:36:23.944Z",
- "from": {
- "type": "CUSTOMER",
- "id": "qe4WxGejR2miAtCcTAaA4w"
}, - "sessionId": "dGwbXv5RR8SjbEln5YlKaQ",
- "type": "TEXT",
}
]Get Automation Message
Returns the message with the provided messageId within the automation session with the provided sessionId.
path Parameters
| sessionId required | string Example: pOVVdzweSumI4bFxjlT8LA Id of the automation session. |
| messageId required | string Example: 62723418e0374c00f31c4ca7 Id of the message. |
Responses
Automation session message
Message with the given messageId does not exist in the given automation session.
Response samples
- 200
- 404
{- "id": "626c058b82388c00f4770ede",
- "content": {
- "value": "How can I help you?"
}, - "createdAt": "2022-05-04T06:36:23.944Z",
- "from": {
- "type": "CUSTOMER",
- "id": "qe4WxGejR2miAtCcTAaA4w"
}, - "sessionId": "dGwbXv5RR8SjbEln5YlKaQ",
- "type": "TEXT",
}Agent Handoff
Handoff communication of the automation session, given sessionId, to an agent. If successful, returns nothing.
path Parameters
| sessionId required | string Example: pOVVdzweSumI4bFxjlT8LA Id of the automation session. |
Request Body schema: application/json
Handoff to agent.
| description required | string [ 1 .. 240 ] characters A brief description why the session was handed off to an agent. Cannot be blank. |
Responses
The handoff is successful.
Failed to handoff to agent.
Request samples
- Payload
{- "description": "Could not handle request. Hand off to agent."
}Response samples
- 400
{- "errors": [
- {
- "code": "not_exist",
- "detail": "entity does not exist"
}
]
}Close Automation Session
Closes the automation session for the given sessionId. Returns nothing if successful.
path Parameters
| sessionId required | string Example: pOVVdzweSumI4bFxjlT8LA Id of the automation session. |
Request Body schema: application/json
Close the automation session.
| description required | string [ 1 .. 240 ] characters A brief description why the session was closed. Cannot be blank. |
Responses
Automation session was successfully closed.
Failed to close the given automation session.
Request samples
- Payload
{- "description": "Customer not responding. Close session."
}Response samples
- 400
{- "errors": [
- {
- "code": "not_exist",
- "detail": "entity does not exist"
}
]
}Response samples
- 200
{- "id": "ihKsWxiZCDVtXg1iwVmT9Q",
- "loginDomain": "organization.com",
- "name": "My Organization",
- "timezone": "America/Los_Angeles",
}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.
Create recipient collection for an existing proactive campaign
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.
path Parameters
| campaignId required | string Example: yQ16L_YURROhXAg3KzkuYQ id of the campaign to create a new recipient collection for |
Request Body schema: application/json
| name required | string Name for recipient collection |
| startAfter required | string <RFC3339> The time after which the recipient collection should start processing |
| endBefore | string <RFC3339> The time before which the recipient collection should stop processing |
| recipients required | Array of Email Recipients (object) or SMS Recipients (object) or Voice Recipients (object) |
Responses
created recipient collection
campaign not found
Request samples
- Payload
{- "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"
}
]
}Response samples
- 200
- 404
{- "id": "oiaFOojmQu2v8CRQaVUIjw",
- "campaignId": "qmkz789yRyO6BdC8WeEitA",
- "type": "EMAIL",
- "startAfter": "2019-02-21T07:15:19.07272933Z",
- "endBefore": "2019-02-21T07:15:19.07272933Z",
- "name": "My Collection",
- "status": "ACTIVE"
}A Report in Gladly contains metrics that you need to run the contact center. Reports API allows you to access Gladly's reports programatically.
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 section of the help docs.
Request Body schema: application/json
Parameters describing the report to generate.
| metricSet required | string Enum: "AgentAwayTimeReport" "AgentDurationsReport" "AgentDurationsReportV2" "AgentLoginTimeReport" "AgentSummary" "AgentSummaryV2" "AgentSummaryGlanceReport" "AgentSummaryGlanceReportV2" "AgentTimestampsReport" "FirstContactResolutionByAgentV2Report" "PaymentsByAgentReport" "WorkSessionEventsReportV3" "WorkSessionsReport" "WorkSessionsReportV3" "AnswerUsageReport" "AnswerUsageByAgentReport" "ChannelMixReportV2" "ChannelWaitTimeReport" "ChannelWaitTimeReportV2" "ContactExportReport" "ContactExportReportV2" "ContactExportReportV3" "ContactSummaryReport" "ContactSummaryReportV2" "ContactSummaryCountsReport" "ContactSummaryDurationsReport" "ContactSummaryDurationsReportV2" "ContactTimestampsReport" "ConversationExportReport" "ConversationSummaryReport" "ConversationTimestampsReport" "AbandonedCallsInIVRReport" "AutoThrottleMissedConversationsReport" "IVRExecutiveSummaryReportV2" "IvrEndStatesReportV2" "PaymentsSummaryReport" "ProactiveVoiceSummaryReport" "TopicHierarchyReport" "TaskExportReport" "TaskSummaryReport" "TaskTimestampsReport" "TopicSummaryReport" "AutoThrottleChangesReport" "ChatDisplayPctChangesReport" "HelpCenterAnswerSearchReport" "HelpCenterAnswerUsageReport" "QuickActionsUsageReport" "SelfServiceThreadsReport" "SidekickAssistsByClassificationTopicReport" "GladAppAnswerSearchReport" "GladAppAnswerUsageReport" "GladAppContactPointsReport" 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 section of the help docs. |
| timezone | string 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. |
| startAt required | string 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 |
| endAt required | string 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 The date should be in the format |
| aggregationLevel | string Default: "daily" Enum: "halfHourly" "daily" "weekly" "monthly" "quarterly"
Applies to the following Note that an individual aggregationLevel may only be available depending on the |
| filters | object Additional filters that can be applied to the report. Each filter applies to select |
Responses
Report CSV
Invalid request
Request samples
- Payload
{- "metricSet": "ContactSummaryReport",
- "timezone": "America/Los_Angeles",
- "startAt": "2021-10-01",
- "endAt": "2021-10-02",
- "aggregationLevel": "daily",
- "filters": {
- "channel": "allChannels",
- "inboxes": [
- "c23d738960f946988e943f400313133a",
- "2c475a4351ce4aa39ff5cb9f526d77db"
]
}
}Response samples
- 400
{- "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"
}
]
}Generate a work session report
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 as other Gladly reports
This CSV file contains the following columns, whose definitions may be viewed via the 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 schema: application/json
A time range for the report that will be generated.
| startAtTime required | string Starting time of the report interval The date should be in ISO 8601 format |
| endAtTime required | string 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 |
Responses
Work Session Report CSV
Bad Request
Request samples
- Payload
{- "startAtTime": "2020-04-13T19:27-09:00",
- "endAtTime": "2020-04-14T19:27-09:00"
}Response samples
- 400
{- "errors": [
- {
- "attr": "startAtTime",
- "code": "invalid",
- "detail": "endAtTime must occur after startAtTime"
}
]
}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.
Create task
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 schema: application/json
Task to create
| id | string <= 50 characters Specifies the id of the task |
| assignee required | object (Assignee) Inbox and agent assignee for a task |
| body required | string <= 10000 characters Text to describe what task to complete. Constrained HTML Rich Content is supported. |
| dueAt required | string <RFC3339> Time when the task will be due. This must be set to a time in the future. |
| customer required | object (Customer Specification) Specifies the customer a task belongs to. You must provide exactly one of the values. |
Responses
task created
Invalid field(s) in request body
Request samples
- Payload
{- "id": "pOVVdzweSumI4bFxjlT8LA",
- "assignee": {
- "inboxId": "NFpDZtfqhk2pI6fjaVDlFf",
- "agentId": "zGaHXjD4SR-moMR9LbULDa"
}, - "body": "Call customer back with information about booking",
- "dueAt": "2020-03-15T06:13:00.125Z",
- "customer": {
- "emailAddress": "michelle.smith@example.org",
- "mobilePhone": "+16505551987"
}
}Response samples
- 400
{- "errors": [
- {
- "attr": "content",
- "code": "blank",
- "detail": "content cannot be blank"
}
]
}Create task for customer
Add a task to an existing customer's conversation timeline
path Parameters
| customerId required | string Id of the customer associated with the task to create. You can look up the id using the Find customers API. |
Request Body schema: application/json
Create Task
| id | string <= 50 characters Unique task id. Must be URL safe and under 50 characters. An id will be automatically generated if one is not included. |
| assignee required | object (Assignee) Inbox and agent assignee for a task |
| body required | string <= 10000 characters Text to describe what task to complete. Constrained HTML Rich Content is supported. |
| dueAt required | string <RFC3339> Time when the task will be due. This must be set to a time in the future. |
Responses
task created
Invalid field(s) in request body
Customer with customerId does not exist
Specified id is in use
Request samples
- Payload
{- "id": "pOVVdzweSumI4bFxjlT8LA",
- "assignee": {
- "inboxId": "NFpDZtfqhk2pI6fjaVDlFf",
- "agentId": "zGaHXjD4SR-moMR9LbULDa"
}, - "body": "Call customer back with information about booking",
- "dueAt": "2020-03-15T06:13:00.125Z"
}Response samples
- 400
- 404
- 409
{- "errors": [
- {
- "attr": "content",
- "code": "blank",
- "detail": "content cannot be blank"
}
]
}List tasks
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.
path Parameters
| customerId required | string Id of the customer whose tasks you'd like to view. |
query Parameters
| status | string Enum: "OPEN" "CLOSED" Fetch tasks with the provided status. |
Responses
Array of tasks
Invalid input
A customer with the given id does not exist
Response samples
- 200
- 400
- 404
[- {
- "id": "pOVVdzweSumI4bFxjlT8LA",
- "customerId": "gHufx-U3QqOmhvFuViceTw",
- "timestamp": "2019-07-03T04:30:12.07Z",
- "createdBy": {
- "id": "gHufx-U3QqOmhvFuViceTw",
- "type": "CUSTOMER"
}, - "assignee": {
- "inboxId": "NFpDZtfqhk2pI6fjaVDlFf",
- "agentId": "zGaHXjD4SR-moMR9LbULDa"
}, - "body": "Call customer back with information about booking",
- "dueAt": "2020-03-15T06:13:00.125Z",
- "status": "OPEN"
}
]Update task
Update an existing task
path Parameters
| taskId required | string Id of the task that is to be updated |
Request Body schema: application/json
Task properties to create
| status | string Enum: "OPEN" "CLOSED" |
| body | string <= 10000 characters Text to describe what task to complete. Constrained HTML Rich Content is supported. |
| dueAt | string <RFC3339 with millis> Due date of task |
| assignee | object (Assignee) Inbox and agent assignee for a task |
Responses
The task was created task
Invalid field(s) in request body
Task with taskId does not exist.
Request samples
- Payload
{- "status": "OPEN",
- "body": "Call customer back with information about booking",
- "dueAt": "2021-04-11T14:09:23.000Z",
- "assignee": {
- "inboxId": "NFpDZtfqhk2pI6fjaVDlFf",
- "agentId": "zGaHXjD4SR-moMR9LbULDa"
}
}Response samples
- 400
- 404
{- "errors": [
- {
- "attr": "content",
- "code": "blank",
- "detail": "content cannot be blank"
}
]
}Get task
Get task
path Parameters
| taskId required | string Id of the task requested |
Responses
Returns requested task
Given task id does not exist
Response samples
- 200
- 404
{- "id": "pOVVdzweSumI4bFxjlT8LA",
- "customerId": "gHufx-U3QqOmhvFuViceTw",
- "timestamp": "2019-07-03T04:30:12.07Z",
- "createdBy": {
- "id": "gHufx-U3QqOmhvFuViceTw",
- "type": "CUSTOMER"
}, - "assignee": {
- "inboxId": "NFpDZtfqhk2pI6fjaVDlFf",
- "agentId": "zGaHXjD4SR-moMR9LbULDa"
}, - "body": "Call customer back with information about booking",
- "dueAt": "2020-03-15T06:13:00.125Z",
- "status": "OPEN"
}Add task comment
Create a comment on a task. Note that you can’t create comments on closed tasks.
path Parameters
| taskId required | string Id of the task that will be commented on. |
Request Body schema: application/json
Add comment to task
| id | string <= 50 characters Unique comment id. Must be URL safe and under 50 characters. An id will be automatically generated if one is not included. |
| agentId required | string the id of the agent making the comment |
| comment | string <= 10000 characters Comment body |
Responses
comment added
Invalid field(s) in request body
Task with taskId does not exist
Request samples
- Payload
{- "id": "pOVVdzweSumI4bFxjlT8LA",
- "agentId": "dzweSumI4bFxjlT8LApOVV",
- "comment": "Return call to customer"
}Response samples
- 400
- 404
{- "errors": [
- {
- "attr": "content",
- "code": "blank",
- "detail": "content cannot be blank"
}
]
}Get task comments
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.
path Parameters
| taskId required | string Id of the task comments are requested for. |
Responses
All comments that belong to task
Task with taskId does not exist
Response samples
- 200
- 404
[- {
- "id": "pOVVdzweSumI4bFxjlT8LA",
- "agentId": "dzweSumI4bFxjlT8LApOVV",
- "comment": "Return call to customer.",
- "taskId": "dzweSumI4bFxjlT8LApOVV",
- "createdAt": "2020-03-15T06:13:00.125Z"
}
]Get task comment
Get task comment.
path Parameters
| taskId required | string Task id |
| commentId required | string Comment id |
Responses
Returns task comment
Comment with commentId does not exist
Response samples
- 200
- 404
{- "id": "pOVVdzweSumI4bFxjlT8LA",
- "agentId": "dzweSumI4bFxjlT8LApOVV",
- "comment": "Return call to customer.",
- "taskId": "dzweSumI4bFxjlT8LApOVV",
- "createdAt": "2020-03-15T06:13:00.125Z"
}A Team represents a group of Agents. They may handle particular Inboxes or types of work within Gladly.
Response samples
- 200
[- {
- "id": "ovg2jQCQS9ScsDkBxG-o2Q",
- "name": "Stay Advisors",
- "description": "Team to answer customer questions about new bookings",
- "agentIds": [
- "WmeA3Y51Q5ayCAaZ1AotIA"
]
}
]Get team
Get a team by its unique id.
path Parameters
| teamId required | string Example: ovg2jQCQS9ScsDkBxG-o2Q id of the team |
Responses
Team
Response samples
- 200
{- "id": "ovg2jQCQS9ScsDkBxG-o2Q",
- "name": "Stay Advisors",
- "description": "Team to answer customer questions about new bookings",
- "agentIds": [
- "WmeA3Y51Q5ayCAaZ1AotIA"
]
}Create a User Identity JWT
Create a User Identity JWT for a customer. The JWT is used to authenticate the customer with Glad App. The JWT contains the customer identity information.
Request Body schema: application/json
Customer Identity Information
| identityType | string Enum: "EMAIL" "MOBILE_PHONE_NUMBER" The type of identity information |
| identity | string The identity information, the value depends on the identityType field. Needs to be a valid email or phone number format (E.164). |
Responses
customer created
error creating JWT
Request samples
- Payload
{- "identityType": "EMAIL",
- "identity": "test@example.com"
}Response samples
- 200
- 400
{- "token": "string"
}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 to learn more about Hierarchical Topics.
Response samples
- 200
{- "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"
}
]
}Add Topic
Add a Topic to the list of available Topics.
Request Body schema: application/json
Topic to create
| id | string unique Topic id - optional (a new id will be generated if not provided) |
| name required | string Name of the Topic - must be unique |
| disabled | boolean If the Topic is not in use - optional, defaults to false |
| parentId | string id of parent Topic, if the Topic is nested under another topic - optional |
Responses
Topic Created
Bad Request
Topic contains conflicting values
Request samples
- Payload
{- "id": "uu4t00vITaKQ3bVjU2UrGQ",
- "name": "Order Returns",
- "disabled": false,
- "parentId": "ChefeoTHSlaIbKg57H5R9Q"
}Response samples
- 400
- 409
{- "errors": [
- {
- "attr": "id",
- "code": "invalid",
- "detail": "id contains unsupported characters"
}
]
}Get Topic
Get a Topic by its unique id.
path Parameters
| topicId required | string Example: uu4t00vITaKQ3bVjU2UrGQ id of the Topic |
Responses
Topic
Given Topic id does not exist
Response samples
- 200
- 404
{- "id": "uu4t00vITaKQ3bVjU2UrGQ",
- "name": "Order Returns",
- "disabled": false,
- "parentId": "ChefeoTHSlaIbKg57H5R9Q"
}Update Topic
Update an existing Topic.
path Parameters
| topicId required | string Example: uu4t00vITaKQ3bVjU2UrGQ id of the Topic |
Request Body schema: application/json
| name required | string Name of the Topic |
| disabled | boolean If the Topic is not in use |
| parentId | string id of parent Topic, if the Topic is nested under another topic - optional |
Responses
Topic updated successfully
Bad Request
Topic with the specified id does not exist
Topic update contains conflicting values
Request samples
- Payload
{- "name": "Order Returns",
- "disabled": false,
- "parentId": "ChefeoTHSlaIbKg57H5R9Q"
}Response samples
- 400
- 404
- 409
{- "errors": [
- {
- "attr": "name",
- "code": "blank",
- "detail": "name cannot be blank"
}
]
}A Webhook is a way to send notifications about Gladly events as a POST request to the endpoint of your choice.
Create webhook
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.
You are limited to 20 webhooks for your organization.
Request Body schema: application/json
Webhook to add
| name | string <= 200 characters friendly name of the webhook |
| events required | Array of strings Items 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" "AUTOMATION/MESSAGE_RECEIVED" "AUTOMATION/MESSAGE_SENT" "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" "CUSTOM_CHANNEL/MESSAGE_SENT" "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" list of events that trigger the webhook. More events are coming soon. Please see Events for more information about the data included for each event type. |
| url required | string your URL that POST requests are sent to when events occur. HTTPS is required and this value must be unique across all webhooks. |
| credentials | object (Basic Auth Credentials) |
| headers | object (HTTP Headers) custom HTTP headers to include in every request |
| enabled | boolean Default: false whether the webhook is delivering notifications |
Responses
Created webhook
Invalid field(s) in request body
Request samples
- Payload
{- "name": "CSAT integration",
- "events": [
- "CONVERSATION/CLOSED"
], - "credentials": {
- "username": "integrations@organization.com",
- "password": "fxdUfTcejVxVs9bQ8DizKccq"
}, - "headers": {
- "X-Gladly-Token": "123"
}
}Response samples
- 400
{- "errors": [
- {
- "attr": "content",
- "code": "blank",
- "detail": "content cannot be blank"
}
]
}Response samples
- 200
[- {
- "id": "a9dIl-kKRrKUZLQtJ-tjtw",
- "name": "CSAT integration",
- "events": [
- "CONVERSATION/CLOSED"
], - "createdAt": "2019-07-03T04:30:12.07Z",
- "updatedAt": "2019-07-09T09:00:10.00Z",
- "hasCredentials": true,
- "headerKeys": [
- "X-Gladly-Key"
], - "enabled": false,
- "disabledAtDueToRetryLimit": "2019-07-10T12:00:00.00Z"
}
]Update webhook
Update webhook by id.
If enabling a webhook or updating a webhook's URL, your service is expected to respond to a Ping Event.
path Parameters
| webhookId required | string Example: a9dIl-kKRrKUZLQtJ-tjtw id of the webhook |
Request Body schema: application/json
JSON patch of webhook properties to insert or update
| name | string <= 200 characters friendly name of the webhook |
| events | Array of strings Items 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" "AUTOMATION/MESSAGE_RECEIVED" "AUTOMATION/MESSAGE_SENT" "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" "CUSTOM_CHANNEL/MESSAGE_SENT" "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" list of events that trigger the webhook. More events are coming soon. Please see Events for more information about the data included for each event type. |
| url | string your URL that POST requests are sent to when events occur. HTTPS is required and this value must be unique across all webhooks. |
| credentials | object (Basic Auth Credentials) |
| headers | object (HTTP Headers) custom HTTP headers to include in every request |
| enabled | boolean Default: false whether the webhook is delivering notifications |
Responses
Updated webhook
Invalid field(s) in request body
Webhook with id does not exist
Request samples
- Payload
{- "enabled": true
}Delete webhook
Delete a webhook by ID
path Parameters
| webhookId required | string Example: a9dIl-kKRrKUZLQtJ-tjtw id of the webhook |
Responses
Webhook deleted
Webhook must be disabled to be deleted
Webhook with id does not exist
Get webhook
Get a webhook by ID
path Parameters
| webhookId required | string Example: a9dIl-kKRrKUZLQtJ-tjtw id of the webhook |
Responses
Webhook
Webhook with id does not exist
Response samples
- 200
{- "id": "a9dIl-kKRrKUZLQtJ-tjtw",
- "name": "CSAT integration",
- "events": [
- "CONVERSATION/CLOSED"
], - "createdAt": "2019-07-03T04:30:12.07Z",
- "updatedAt": "2019-07-09T09:00:10.00Z",
- "hasCredentials": true,
- "headerKeys": [
- "X-Gladly-Key"
], - "enabled": false,
- "disabledAtDueToRetryLimit": "2019-07-10T12:00:00.00Z"
}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 or the Webhooks Admin Page.
Users with API User permissions can configure webhooks by navigating to Integrations > 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.
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.
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 |
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.
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 or the List Items in Conversation API.
Please see the Help Documentation for more information about many of the events listed below.
| Event | Triggered by Gladly when: |
|---|---|
| AGENT_AVAILABILITY/UPDATED | an Agent's availability is updated |
| AGENT_STATUS/CHANGED_ACTIVE_REASON | an Agent's active reason is updated |
| AGENT_STATUS/LOGGED_IN | an Agent logs in |
| AGENT_STATUS/LOGGED_OUT | an Agent logs out |
| AGENT_STATUS/RETURNED_FROM_AWAY | an Agent returns from away |
| AGENT_STATUS/WENT_AWAY | an Agent goes away |
| AUTOMATION/MESSAGE_RECEIVED | an Entry Point that has been configured for Message Automation receives an inbound message |
| CONTACT/ENDED | a Contact is ended |
| CONTACT/FULFILLED | a Contact's SLA is fulfilled |
| CONTACT/HOLD_ENDED | a Contact's hold is ended |
| CONTACT/HOLD_STARTED | a Contact's hold is started |
| CONTACT/JOINED | an Agent joins a Contact |
| CONTACT/MESSAGE_RECEIVED | a Message is received |
| CONTACT/MESSAGE_SENT | a Message is sent |
| CONTACT/OFFER_ACCEPTED | a Contact's offer is accepted |
| CONTACT/OFFERED | a Contact is offered |
| CONTACT/OFFER_REJECTED | a Contact's offer is rejected |
| CONTACT/STARTED | a Contact is started |
| CONTACT/TRANSFERRED | a Contact is transferred |
| CONVERSATION/CLOSED | a Conversation is closed |
| CONVERSATION/CREATED | a new Conversation is created |
| CONVERSATION/CUSTOM_ATTRIBUTE_ADDED | a custom attribute has been added to the conversation |
| CONVERSATION/CUSTOM_ATTRIBUTE_REMOVED | a custom attribute has been removed from the conversation |
| CONVERSATION/NOTE_CREATED | a Note is added to a Conversation |
| CONVERSATION/REOPENED | a Conversation is reopened |
| CONVERSATION/TOPIC_ADDED | a topic is added to a Conversation |
| CONVERSATION/TOPIC_REMOVED | a Conversation's topic is removed |
| CONVERSATION_ASSIGNEE/UPDATED | a Conversation's assignee (inbox and/or Agent) changes |
| CONVERSATION_STATUS/UPDATED | a Conversation changes statuses (e.g.: from OPEN to CLOSED) |
| CUSTOM_CHANNEL/MESSAGE_SENT | an outbound message sent using a Custom Channel |
| CUSTOMER/MERGED | a Customer Profile is merged with another profile |
| CUSTOMER_PROFILE/CREATED | a Customer Profile is created |
| CUSTOMER_PROFILE/DELETED | a Customer Profile is deleted |
| CUSTOMER_PROFILE/MERGED | a Customer Profile is merged with another profile |
| CUSTOMER_PROFILE/UPDATED | a Customer Profile is updated (e.g.: name is updated) |
| EXPORT_JOB/COMPLETED | a data export job is completed |
| EXPORT_JOB/FAILED | a data export job 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 |
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 schema: application/json
the event payload
- Agent Availability Updated
- Agent Changed Active Reason
- Agent Logged In
- Agent Logged Out
- Agent Returned From Away
- Agent Went Away
- Automation Message Received
- Contact Ended
- Contact Fulfilled
- Contact Hold Ended
- Contact Hold Started
- Contact Joined
- Contact Message Received
- Contact Message Sent
- Contact Offer Accepted
- Contact Offer Rejected
- Contact Offered
- Contact Started
- Contact Transferred
- Conversation Assignee Updated
- Conversation Closed
- Conversation Created
- Conversation Custom Attribute Added
- Conversation Custom Attribute Removed
- Conversation Note Created
- Conversation Reopened
- Conversation Status Updated
- Conversation Topic Added
- Conversation Topic Removed
- Custom Channel Message Sent
- Customer Merged
- Customer Profile Created
- Customer Profile Deleted
- Customer Profile Merged (deprecated)
- Customer Profile Updated
- Export Job Completed
- Export Job Failed
- PING
- Payment Request Created
- Payment 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
| id required | string Unique event ID |
| type required | string Value: "AGENT_AVAILABILITY/UPDATED" |
| timestamp required | string <ISO 8601> Time the event was recorded |
| initiator required | object (Initiator) Type and ID (if applicable) of the entity that triggered the event. |
| content required | object (Content) Content for event |
Responses
Success
Web service hosted on your servers should be reachable from the Gladly cluster
Request samples
- Payload
{- "id": "zGaHXjD4SR-moMR9LbULDa",
- "type": "AGENT_AVAILABILITY/UPDATED",
- "timestamp": "2019-07-03T04:30:12.07Z",
- "initiator": {
- "id": "NFpDZtfqhk2pI6fjaVDlFf",
- "type": "AGENT"
}, - "content": {
- "agentId": "zGaHXjD4SR-moMR9LbULDa",
- "availableFor": [
- "MAIL",
- "VOICE"
], - "occurredAt": "2019-07-03T04:30:12.07Z"
}
}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.
Architecture, Setup, Authentication, Sample Requests and More
A detailed overview of Lookup Adaptor architecture, requests, resposnes and more can be found here.
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), or result in a new version that you will need to integrate with afresh (i.e. non-backwards compatible changes).
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}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.
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.
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).
| 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 |
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"}]}The number of requests for an 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.
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.
The 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 |
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.
Ratelimit-Limit-Second
Ratelimit-Remaining-SecondYou 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.
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.
We are continuously expanding Gladly's integration capabilities. To get early access to any of the following features, please contact Gladly Support.
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.
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 to be notified of new developments.