Table of Contents
Store chat message, email, SMS, and more content in your data warehouse to perform further analysis (e.g.: number of chat messages per chat session, custom sentiment analysis you’d like to perform using your own software).
Get Conversation Items from Gladly #
Option 1: Conversation Data Export #
Use the below data as a reference.
URL: GET File API
Filters: N/A
Cadence: 24 hours
Available For: 14 days
Note: This data is 24 hours behind.
Why Use This API? #
This API is great to be able to store messages in bulk as opposed to having to retrieve messages one by one.
Relevant API Notes #
- You might wish to supplement this information with a GET Customer call to get more information (e.g.: custom Attributes) about the customer.
- We recommend doing the above for all Customers in customers.jsonl.
- You might also wish to supplement this information with a GET Conversation API call to retrieve which** inboxId** the conversation is in.
- Inbox IDs can change through the lifetime of a conversation.
- We recommend doing the above for all conversations in conversation_items.jsonl.
- You might also wish to match up against inbox names using GET Inbox API.
- The topics.jsonl and agents.jsonl files show information about topicId and agentId mappings (e.g.: agent email address; topic name applied)
- Items only appear in this export if activities with type documented in the GET file export occur within the export period.
- If data sync fails, files are available for 14 days and are retrievable in the following run.
Data Mappings to Gladly’s Other APIs #
| File name | JSON key | Corresponds to API | Additional information in API not in .jsonl files |
|---|---|---|---|
| agents.jsonl | id | https://developer.gladly.com/rest/#operation/getAgent | N/A – though if interested, you could call https://developer.gladly.com/rest/#operation/getTeams to find the team IDs this Agent belongs to |
| conversation_items.jsonl | id | https://developer.gladly.com/rest/#operation/getItem | N/A |
| conversationId | https://developer.gladly.com/rest/#operation/getConversation | Which inbox the Conversation is currently in, when Conversation is created current Conversation status and what topics are currently applied | |
| customerId | https://developer.gladly.com/rest/#operation/getCustomer | Custom Attributes, phone and email types, create date, updated date | |
| initiator.id | https://developer.gladly.com/rest/#operation/getCustomer if initiator type is CUSTOMER https://developer.gladly.com/rest/#operation/getAgent if initiator type is AGENT initiator.id corresponds to agents.jsonl’s id if initiator type is AGENT initiator.id corresponds to customers.jsonl’s id if initiator type is CUSTOMER | See comments above on GET Customer and GET Agent APIs | |
| responder.id | https://developer.gladly.com/rest/#operation/getCustomer if responder type is CUSTOMER https://developer.gladly.com/rest/#operation/getAgent if responder type is AGENT responder.id corresponds to agents.jsonl’s id if responder type is AGENT responder.id corresponds to customers.jsonl’s id if responder type is CUSTOMER | See comments above on GET Customer and GET Agent APIS | |
| content.addedTopicIds and content.removedTopicIds (only shows when content.type == ‘TOPIC_CHANGE’) | https://developer.gladly.com/rest/#operation/getTopic topics.jsonl file also has this information | API will also show you hierarchy parent IDs for topic, but topics.jsonl will not | |
| customers.jsonl | id | https://developer.gladly.com/rest/#operation/getCustomer | See above comments on GET Customer API |
| topics.jsonl | id | https://developer.gladly.com/rest/#operation/getTopic | See above comments on GET topic API |
Option 2: Subscribe to Webhooks #
Why Use Webhooks? #
Allows you to be notified of events as they happen so that you can store conversation information & text in real-time.
Setup #
You can follow these instructions to create a webhook.
Gladly will perform a POST request to your endpoint when the event occurs.
Your service is expected to respond within 15 seconds.
Webhook Recommendations #
- Subscribe to CONVERSATION/CREATED, CONVERSATION/CLOSED, MESSAGE/RECEIVED, CONVERSATION_ASSIGNEE/UPDATED, CONVERSATION_STATUS/UPDATED to get real-time event updates.
- When you get this event, we recommend using the GET list conversation items API to get the newest conversation items.
- Enter those into your data warehouse and de-duplicate conversation item IDs.
- Unlike the conversation items export described above, you will only receive notifications of change upon the above events.
- If an agent responds five times to a Customer’s email in a row, you will not get pinged with a webhook event, because the status did not change.
