How to Retrieve the Full Ticket Conversation Using the BoldDesk API

BoldDesk enables the export of the entire thread of replies and internal notes directly through the BoldDesk REST API or Webhooks.

This guide details the process to obtain and export the full conversation thread of a ticket, encompassing both public replies and internal notes.

Prerequisites

Before you begin:

Generate an API Key from your BoldDesk account. Learn more about Generate and Manage API Keys in BoldDesk.
Include the API key in your request header.

When listing agents using the API, certain fields like phone number are read-only and may only appear in responses when available; they cannot be used for searching or filtering. To retrieve complete agent details, including phone information, use the Get Agent by Email or Get Agent by ID APIs, provided the agent has these details configured.

1. Retrieve Ticket Details

Then, you need the Ticket ID of the ticket you want to get the details for and run the API to get the details.

GET /api/v1/tickets

By default, BoldDesk returns tickets sorted by LastModifiedOn in descending order. If ticket updates occur between API calls, records may change positions and reappear in paginated results. To maintain consistent ordering and prevent duplicate tickets across pages, always use the OrderBy query parameter, such as CreatedOn. For example, applying order by CreatedOn in descending order: https://yourdomain.bolddesk.com/api/v1/tickets?Q=createdon:{"from":"2025-11-27T18:30:00.000Z","to":"2025-12-04T18:30:00.000Z"}&Q=source:[8]&RequiresCounts=true&BrandIds=6&Page={pageNumber}&PerPage=100&OrderBy=createdOn%20desc

2. Get Public Messages /Retrieve Public Comments

Use the following endpoint to retrieve all public replies on a ticket:

GET /api/v1/tickets/{ticketId}/public-messages

How to Differentiate Customer and Agent Replies in BoldDesk API
When retrieving messages via API, you can differentiate customer vs. agent replies using these fields:

‘IsAgent’ - If label true → Agent reply and if label false → Customer reply.
‘IsUpdatedByCustomer’ - If label true → Customer reply and if label false → Agent reply.

3. Get Internal Notes (Private Messages)

To retrieve internal notes, use the full ticket details endpoint or check for a dedicated internal notes endpoint (if available in your plan):

GET /api/v1/tickets/{ticketId}/messages

Developer API Documentation: Get Internal Notes

4. (Optional) Get Message Stats

If you want to analyze the volume or timing of replies, use:

GET /api/v1/tickets/{ticketId}/public-messages/min-max-stats

Developer API Documentation: Get Message Stats

5. Automate with Webhooks (Optional)

To capture replies and notes in real-time, you can set up a Webhook to send you the ticket updates with the desired details in the payload.
Learn more about How to Create and Manage Webhooks.

How to Detect Ticket History Changes (updatedOn vs lastUpdatedOn)

BoldDesk exposes two timestamps that may not always match exactly because they track changes at different levels.

updatedOn (Histories endpoint)
Use updatedOn from GET /api/v1/tickets/{ticketId}/histories when you only need to detect changes that create history records (status changes and other tracked history events).
lastUpdatedOn (Tickets endpoint)
Use lastUpdatedOn from GET /api/v1/tickets when you need to detect any ticket-level change, including updates that may not create a new history record.
Important behavior
Not every ticket update creates a history record. As a result, small time differences between lastUpdatedOn and the latest history updatedOn can occur and are expected.
Recommended sync approach
- Use history updatedOn to maintain a per-ticket history cursor (MAX updatedOn).
- Use ticket lastUpdatedOn only as a pre-filter to reduce unnecessary /histories calls.

Export Complete Ticket Conversations for a Reporting Period

The standard ticket export does not include the complete conversation history or ticket attachments. To retrieve all ticket conversations for a specific reporting period, use the BoldDesk REST API and process the results using a custom script or external application.

For example, to archive conversations from the previous six months:

Generate a BoldDesk API key.
Retrieve the tickets created or updated within the required date range:
```
GET /api/v1/tickets
```
Use pagination to retrieve every page of matching tickets.
Store the ticket ID returned for each ticket.
Retrieve all messages, including internal notes, for each ticket:
```
GET /api/v1/tickets/{ticketId}/messages
```
If only customer-visible messages are required, retrieve public messages:
```
GET /api/v1/tickets/{ticketId}/public-messages
```
Retrieve the attachment information associated with each message.
Use the documented ticket-attachment operation to download each attachment separately.
Store the retrieved ticket and message data.
Generate the required Excel workbook using the stored data.

BoldDesk returns the API data in JSON format. The API does not directly generate an Excel workbook containing the complete conversation history. Use a custom script or external application to convert the retrieved data into Excel.
Attachments are not embedded in the Excel workbook automatically. Download and store each attachment separately, and include the applicable file name or local reference in the generated report when required.

Troubleshooting Common Errors

401 Unauthorized / 403 Forbidden
- Verify your API key/token is valid and correctly applied.
- Confirm the API credential has permission to access the ticket and its conversations.
404 Not Found
- Confirm the Ticket ID is correct.
- Ensure the ticket exists in the correct workspace/account context.
Empty response or missing public comments
- Confirm the ticket has public comments.
- Check whether the endpoint returns both public and private comments and whether you need to filter by visibility.
429 Too Many Requests
- Reduce request frequency.
- Add retry logic with backoff in your integration.

Frequently Asked Questions

Do I need special permissions to use the BoldDesk API for ticket conversations?
Yes. You must have an API Key generated from your BoldDesk account and appropriate role permissions to access ticket data. Without these, API calls will return 401 Unauthorized.
Can I export the conversation in CSV or PDF format directly from the API?
No. The API returns data in JSON format. You can convert it to CSV or PDF using external tools or scripts after retrieving the data.
Are there rate limits for API calls?
- Yes. BoldDesk enforces rate limits to prevent abuse. If exceeded, you’ll receive:
- 429 Too Many Requests → Wait and retry after the specified time.
Does BoldDesk provide real-time updates for ticket conversations?
Yes. Use Webhooks to receive real-time notifications when a ticket is updated. The webhook payload includes message details.
Why can’t I see public comments in reports?
Public comments are excluded from reports due to performance considerations.
How do I retrieve the full email/thread updates for a ticket via API?
To get the complete ticket timeline via API, combine conversation messages (public replies + internal notes) with field-change history (status/assignee/priority changes, etc.). Use these endpoints:
- Ticket details: GET /api/v1/tickets
- Public replies (thread): GET /api/v1/tickets/{ticketId}/public-messages
- Internal notes: GET /api/v1/tickets/{ticketId}/messages
- Field-change history: GET /api/v1/tickets/{ticketId}/histories

Was this article useful?

Dislike

Comments (0)