# ThriveDesk developer documentation

Developer contracts for the REST API, Assistant SDK, webhooks, and SmartApp.

- Help center (merchant and product setup): https://help.thrivedesk.com/llms.txt
- Bundled OpenAPI 3.1 specification: https://developer.thrivedesk.com/openapi/bundled.yaml
- Full developer corpus: https://developer.thrivedesk.com/llms-full.txt

# ThriveDesk Developer Docs

- Get started: Build with ThriveDesk.
  - [Get started](/get-started): REST API, Assistant SDK, webhook, SmartApp, integration guide, and machine-readable contracts.
  - [Quickstart](/get-started/quickstart): Create an access token, inspect your account, retrieve conversations, and send a reply.
  - [Authentication and scopes](/get-started/authentication): Authenticate with workspace-scoped bearer tokens and understand the current access model.
  - [Errors](/get-started/errors): Error response envelopes, HTTP status behavior, validation failures, and machine-readable auth codes.
  - [Pagination and rate limits](/get-started/pagination): Pagination envelopes, supported list parameters, throttling tiers, and retry behavior.
  - [Idempotency and safe retries](/get-started/idempotency): Prevent duplicate conversations, replies, and other writes when a request must be retried.
  - [Versioning and deprecation](/get-started/versioning): Understand the API version, compatibility promises, deprecation notices, and upgrade workflow.
  - [Changelog](/get-started/changelog): Every change to the documented ThriveDesk Public API surface, newest first.
- API reference: Explore REST APIs.
  - [API reference](/api): Explore every public ThriveDesk API operation, request field, response schema, and example.
  - Attachments
    - [Delete an attachment](/api/attachments/attachments-delete-delete): Delete an attachment.
    - [Download an attachment (binary stream)](/api/attachments/attachments-download-get): Download an attachment (binary stream).
    - [Upload attachments to a conversation draft](/api/attachments/attachments-store-post): Upload attachments to a conversation draft.
  - Business hours
    - [List business-hours profiles](/api/business-hours/business-hours-index-get): List business-hours profiles.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Create a business-hours profile](/api/business-hours/business-hours-index-post): Administrators and the account owner only.

An inbox channel belongs to at most one profile. Binding one that another profile already covers returns 422 carrying `conflicting_business_hour_id`, `inbox_id`, and `channel` in place of the usual `errors` object, and the whole write is rolled back.

Under `calendar_24_7` the server stores `schedule` and `schedule_type` as null whatever the payload carries.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Delete a business-hours profile](/api/business-hours/business-hours-resource-delete): Administrators and the account owner only. Permanent, and it releases every inbox channel the profile covered.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [View a business-hours profile](/api/business-hours/business-hours-resource-get): View a business-hours profile.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Update a business-hours profile](/api/business-hours/business-hours-resource-patch): Administrators and the account owner only.

An inbox channel belongs to at most one profile. Binding one that another profile already covers returns 422 carrying `conflicting_business_hour_id`, `inbox_id`, and `channel` in place of the usual `errors` object, and the whole write is rolled back.

Under `calendar_24_7` the server stores `schedule` and `schedule_type` as null whatever the payload carries.

Omitted keys keep their stored value and an explicit `null` is ignored rather than clearing the field. Sending `inbox_channels` replaces the whole set.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
  - Contacts
    - [List conversations for a contact](/api/contacts/contacts-conversations-get): List conversations for a contact.
    - [List contacts](/api/contacts/contacts-index-get): List contacts.
    - [Create a contact](/api/contacts/contacts-index-post): Create a contact.
    - [View a contact](/api/contacts/contacts-resource-get): View a contact.
    - [Update a contact](/api/contacts/contacts-resource-patch): Update a contact.
  - Conversations
    - [Change the contact on a conversation](/api/conversations/conversation-change-contact-patch): Change the contact on a conversation.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Update custom field values on a conversation](/api/conversations/conversation-custom-fields-patch): Update custom field values on a conversation.
    - [Create or update the reply draft](/api/conversations/conversation-draft-post): Create or update the reply draft.
    - [Permanently delete a conversation](/api/conversations/conversation-force-delete-delete): Irreversible. The conversation must already be in the trash, so soft-delete it with `DELETE /v1/conversation/{conversation_id}` first; calling this on a live conversation returns 404.

Everything hanging off the conversation goes with it: thread events, messages, attachments and the files behind them in object storage, tag links, and custom field values. There is no restore afterwards.

Trashed conversations are also purged automatically once they pass the organization's trash lifetime (30 days by default).

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Forward a conversation](/api/conversations/conversation-forward-post): Forward a conversation.
    - [Merge other conversations into this one](/api/conversations/conversation-merge-post): Merge other conversations into this one.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Get thread messages for a conversation](/api/conversations/conversation-messages-get): Get thread messages for a conversation.
    - [Move a conversation to another inbox](/api/conversations/conversation-move-post): Move a conversation to another inbox.
    - [Add an internal note](/api/conversations/conversation-note-post): Add an internal note.
    - [Reply to a conversation](/api/conversations/conversation-reply-post): Reply to a conversation.
    - [Schedule a reply](/api/conversations/conversation-reply-schedule-post): Schedule a reply.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Cancel a scheduled reply](/api/conversations/conversation-reply-unschedule-delete): Cancel a scheduled reply.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Delete a conversation](/api/conversations/conversation-resource-delete): Delete a conversation.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [View a conversation](/api/conversations/conversation-resource-get): View a conversation.
    - [Update a conversation](/api/conversations/conversation-resource-patch): Update a conversation.
    - [Restore a trashed conversation](/api/conversations/conversation-restore-patch): Restore a trashed conversation.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Send a scheduled reply now](/api/conversations/conversation-scheduled-send-now-post): Send a scheduled reply now.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Update a scheduled reply](/api/conversations/conversation-scheduled-update-patch): Update a scheduled reply.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Snooze a conversation](/api/conversations/conversation-snooze-put): Snooze a conversation.
    - [Unmark a conversation as spam](/api/conversations/conversation-spam-delete): Unmark a conversation as spam.
    - [Mark a conversation as spam](/api/conversations/conversation-spam-post): Mark a conversation as spam.
    - [Split a conversation at a message](/api/conversations/conversation-split-post): Split a conversation at a message.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Detach a tag](/api/conversations/conversation-tags-delete): Detach a tag.
    - [Attach a tag](/api/conversations/conversation-tags-post): Attach a tag.
    - [Unsnooze a conversation](/api/conversations/conversation-unsnooze-delete): Unsnooze a conversation.
    - [Update a conversation's priority](/api/conversations/conversation-update-priority-put): Update a conversation's priority.
    - [List conversations assigned to the current user](/api/conversations/conversations-mine-get): List conversations assigned to the current user.
  - Holidays
    - [List holidays](/api/holidays/holidays-index-get): List holidays.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Create a holiday](/api/holidays/holidays-index-post): Administrators and the account owner only. Ranges may overlap an existing holiday.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Delete a holiday](/api/holidays/holidays-resource-delete): Administrators and the account owner only. The holiday stops applying immediately and drops out of the list.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [View a holiday](/api/holidays/holidays-resource-get): View a holiday.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Update a holiday](/api/holidays/holidays-resource-patch): Administrators and the account owner only.

When only one date is sent the range is checked against the stored value for the other. A range violation is always reported under `end_date`, even when `start_date` is the field that moved.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
  - Inboxes
    - [List automations](/api/inboxes/inbox-automations-index-get): List automations.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Delete an automation](/api/inboxes/inbox-automations-resource-delete): Requires the `delete_automations` permission. Permanent: the automation is removed outright, and conversations it already acted on keep those changes. Creating and updating automations is not part of this surface.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [View an automation](/api/inboxes/inbox-automations-resource-get): View an automation.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Soft-delete many conversations](/api/inboxes/inbox-batch-delete-post): Soft-delete many conversations.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Restore many trashed conversations](/api/inboxes/inbox-batch-restore-post): Restore many trashed conversations.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Bulk update conversations](/api/inboxes/inbox-batch-update-post): Bulk update conversations.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Start a new conversation in an inbox](/api/inboxes/inbox-conversations-store-post): Start a new conversation in an inbox.
    - [Create a custom field](/api/inboxes/inbox-custom-fields-index-post): Create a custom field.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Delete a custom field](/api/inboxes/inbox-custom-fields-resource-delete): Delete a custom field.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Update a custom field](/api/inboxes/inbox-custom-fields-resource-patch): Update a custom field.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Delete a custom view](/api/inboxes/inbox-custom-views-resource-delete): Only the teammate who owns the view may delete it, the account owner included. Permanent, and it removes the view for everyone it was shared with. Listing and creating custom views is not part of this surface, so the identifier has to come from a first-party client.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [List saved replies for an inbox](/api/inboxes/inbox-saved-replies-get): List saved replies for an inbox.
    - [List tags assigned in an inbox](/api/inboxes/inbox-tags-get): List tags assigned in an inbox.
    - [List inboxes](/api/inboxes/inboxes-index-get): List inboxes.
    - [List conversations in an inbox](/api/inboxes/inboxes-resource-get): List conversations in an inbox.
    - [Filter conversations in an inbox](/api/inboxes/inboxes-resource-post): Filter conversations in an inbox.
  - Knowledge base
    - [List articles](/api/knowledge-base/knowledgebase-articles-index-get): List articles.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [View an article](/api/knowledge-base/knowledgebase-articles-show-get): View an article.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [List knowledge bases](/api/knowledge-base/knowledgebase-index-get): List knowledge bases.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Create a knowledge base](/api/knowledge-base/knowledgebase-index-post): Create a knowledge base.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Delete a knowledge base](/api/knowledge-base/knowledgebase-resource-delete): Delete a knowledge base.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [View a knowledge base](/api/knowledge-base/knowledgebase-resource-get): View a knowledge base.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Update a knowledge base](/api/knowledge-base/knowledgebase-resource-post): Update a knowledge base.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Remove a knowledge base member](/api/knowledge-base/knowledgebase-users-delete-delete): Revokes one person's access to the help center. The ThriveDesk user account is untouched, and re-inviting them restores access. Proxied to the help-center service, so the status and body are whatever it returns. Listing and inviting members is not part of this surface.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
  - Messages and notes
    - [View a single message body](/api/messages-and-notes/messages-resource-get): View a single message body.
    - [Update a message](/api/messages-and-notes/messages-resource-put): Update a message.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Delete a note](/api/messages-and-notes/notes-resource-delete): Delete a note.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
    - [Update a note](/api/messages-and-notes/notes-resource-put): Update a note.

Personal access token only. The API supports a second, partner-issued token class that is not part of the public surface. This endpoint does not accept that class.
  - Misc
    - [Get current user, organization, and badge counts](/api/misc/me-get): Get current user, organization, and badge counts.
    - [Search conversations](/api/misc/search-post): Search conversations.
  - Reports
    - [Agent leaderboard](/api/reports/reports-agents-get): Agent leaderboard.
    - [Conversation volume report](/api/reports/reports-conversations-get): Conversation volume report.
    - [Happiness ratings report](/api/reports/reports-happiness-get): Happiness ratings report.
    - [Productivity report](/api/reports/reports-productivity-get): Productivity report.
  - Saved replies
    - [List saved replies](/api/saved-replies/saved-replies-index-get): List saved replies.
    - [Create a saved reply](/api/saved-replies/saved-replies-index-post): Create a saved reply.
    - [Delete a saved reply](/api/saved-replies/saved-replies-resource-delete): Delete a saved reply.
    - [Update a saved reply](/api/saved-replies/saved-replies-resource-put): Update a saved reply.
  - Tags
    - [List tags](/api/tags/tags-index-get): List tags.
    - [Create a tag](/api/tags/tags-index-post): Create a tag.
    - [Merge tags into one](/api/tags/tags-merge-post): Merge tags into one.
    - [Delete a tag](/api/tags/tags-resource-delete): Delete a tag.
    - [Update a tag](/api/tags/tags-resource-put): Update a tag.
  - Users
    - [List teammates and pending invitations](/api/users/settings-users-index-get): List teammates and pending invitations.
    - [View a teammate](/api/users/settings-users-resource-get): View a teammate.
- Assistant SDK: Embed customer support.
  - [Assistant SDK overview](/assistant/overview): Install the ThriveDesk Assistant and control the customer-facing widget from JavaScript.
  - [Initialization and ready callback](/assistant/initialization): Initialize the Assistant with or without its launcher and wait until it is safe to call methods.
  - [Assistant methods reference](/assistant/methods): Control the ThriveDesk Assistant programmatically through its global JavaScript API.
  - [Events and lifecycle](/assistant/events): Coordinate application code with the Assistant ready callback and DOM connection event.
  - [Identify users safely](/assistant/identify): Prefill visitor details without treating browser-supplied identity as authentication.
  - [Pass custom customer data](/assistant/custom-data): Understand which visitor fields the public Assistant API accepts and where richer data belongs.
  - [Styling and CSS overrides](/assistant/styling): Inject scoped CSS after the Assistant Shadow DOM is connected.
  - [Content Security Policy](/assistant/csp): Permit the Assistant without weakening the rest of your site's Content Security Policy.
  - [Assistant troubleshooting](/assistant/troubleshooting): Diagnose loading, initialization, method, styling, and session problems.
- Webhooks: Receive signed events.
  - [Webhooks overview and setup](/webhooks/overview): Receive conversation changes from ThriveDesk instead of polling the REST API.
  - [Webhook events and payloads](/webhooks/events): Event names and the version-one conversation payload delivered by ThriveDesk webhooks.
  - [Verify webhook signatures](/webhooks/signatures): Authenticate ThriveDesk webhook requests with X-TD-SIGNATURE and constant-time comparison.
  - [Retries, failures, and replay](/webhooks/retries): Acknowledge deliveries safely and design handlers for duplicate or failed webhook requests.
  - [Webhook debugging](/webhooks/debugging): Diagnose missing deliveries, signature mismatches, timeouts, and duplicate processing.
- SmartApp: Display customer data.
  - [SmartApp overview and concepts](/smartapp/overview): Show data from your service beside a ThriveDesk conversation for the agent handling it.
  - [SmartApp callback contract](/smartapp/callback-contract): Design a stable JSON endpoint for dynamic parameters and the SmartApp builder.
  - [SmartApp output components](/smartapp/output-components): Render scalar values and nested arrays with text fields and repeaters.
  - [SmartApp authentication](/smartapp/authentication): Protect a SmartApp callback without exposing reusable credentials to customers or agents.
  - [SmartApp testing and simulation](/smartapp/testing): Validate dynamic parameters, response data, selectors, nesting, and failure behavior before installation.
  - [SmartApp troubleshooting](/smartapp/troubleshooting): Diagnose connection tests, missing values, repeater mappings, authorization, and stale panels.
- Guides: Build integrations.
  - [Sync conversations to your system](/guides/sync-conversations): Combine signed webhooks with REST reconciliation to maintain a reliable local conversation view.
  - [Create tickets from your app](/guides/create-tickets): Start a ThriveDesk conversation from a server-side application without exposing an API token.
  - [Build a customer portal](/guides/customer-portal): Expose a narrow server-side support experience without leaking ThriveDesk credentials.
  - [Bulk import and backfill](/guides/bulk-import): Import contacts or conversations safely within API limits and without duplicate writes.
  - [Search and filter conversations](/guides/search-filter): Choose between inbox filters, contact history, current-user lists, and global search.
- Resources: Tools and support.
  - [Code samples](/resources/code-samples): Make the same authenticated API request with cURL, JavaScript, PHP, and Python.
  - [Postman and Insomnia](/resources/collections): Import the generated collection or OpenAPI document into your preferred API client.
  - [SDKs](/resources/sdks): Use and regenerate the TypeScript, Python, PHP, and Go clients generated from the OpenAPI specification.
  - [Sandbox and testing](/resources/sandbox): Test integrations safely when the public API has no documented sandbox mode.
  - [Support and contact](/resources/support): Gather actionable diagnostics and contact ThriveDesk about a developer integration.
  - [AI and machine-readable documentation](/resources/ai): Discover the developer and help-center indexes intended for AI agents and retrieval systems.