# ThriveDesk developer documentation
Merchant and product setup documentation: https://help.thrivedesk.com/llms.txt
OpenAPI 3.1 specification: https://developer.thrivedesk.com/openapi/bundled.yaml
# API reference (/api)
The ThriveDesk Public API exposes **90 operations** across conversations, contacts,
inboxes, tags, saved replies, reports, the Knowledge Base, attachments, messages,
notes, business hours, holidays, and account utilities.
Send every request to `https://api.thrivedesk.com/v1` with an `Authorization: Bearer YOUR_API_KEY` header.
## Explore the API [#explore-the-api]
Use the navigation to browse operations grouped by resource. Each operation page includes:
* path, method, parameters, and request-body fields;
* response schemas and examples;
* generated examples for cURL, JavaScript, Python, Go, Java, C#, and Rust;
* an interactive request playground with bearer-token support.
## Machine-readable downloads [#machine-readable-downloads]
* [Bundled OpenAPI 3.1 specification](/openapi/bundled.yaml)
* [Postman collection](/api.postman_collection.json)
* [LLM index](/llms.txt)
# Content Security Policy (/assistant/csp)
Use the exact script and network origins shown by the current installation snippet and your browser's
CSP reports. The public Assistant contract does not publish a permanent origin allowlist, so a copied
list can become stale as delivery infrastructure changes.
## Rollout procedure [#rollout-procedure]
1. Install the Assistant on a staging origin.
2. Enable `Content-Security-Policy-Report-Only`.
3. Load every enabled screen: home, Chat, Contact, Order Status, and Knowledge Base.
4. Add only the blocked ThriveDesk origins to `script-src`, `connect-src`, `img-src`, and `style-src`.
5. Repeat with an authenticated and anonymous browser before enforcing the policy.
```http
Content-Security-Policy-Report-Only:
default-src 'self';
script-src 'self' https://ASSISTANT_SCRIPT_ORIGIN;
connect-src 'self' https://ASSISTANT_API_ORIGIN wss://ASSISTANT_REALTIME_ORIGIN;
img-src 'self' data: https://ASSISTANT_ASSET_ORIGIN;
style-src 'self' 'unsafe-inline';
report-uri /csp-reports
```
Replace every placeholder from observed requests; do not deploy the example literally. Avoid `*`,
and never add `unsafe-eval` just to silence an unrelated console error.
## Related [#related]
* [Assistant troubleshooting](/assistant/troubleshooting)
* [Assistant installation](/assistant/overview)
# Pass custom customer data (/assistant/custom-data)
The currently documented `identify` contract accepts `name` and `email`.
```js
Assistant('identify', {
name: 'Jane Cooper',
email: 'jane@example.com'
});
```
Arbitrary attributes are not part of the published Assistant JavaScript contract. Do not assume an
extra property will be stored or shown to agents.
For richer customer context, expose an authenticated server endpoint and render its response through
a [SmartApp](/smartapp/overview), or store supported contact/custom-field data through the
[REST API](/api).
## Related [#related]
* [Identify users safely](/assistant/identify)
* [SmartApp callback contract](/smartapp/callback-contract)
# Events and lifecycle (/assistant/events)
Two lifecycle hooks are publicly documented: the `ready` command callback and the
`tdAssistantConnected` DOM event.
## Ready callback [#ready-callback]
Use `ready` for SDK commands that require the Assistant to be initialized.
```js
Assistant('ready', () => {
Assistant('identify', currentCustomer);
Assistant('open');
});
```
## DOM connection event [#dom-connection-event]
Use `tdAssistantConnected` when code needs the rendered `` element or its
Shadow DOM.
```js
document.addEventListener('tdAssistantConnected', (event) => {
const assistantElement = event.target;
console.log('Assistant element connected', assistantElement);
});
```
Register the listener before initialization so a fast load cannot race past it.
Public documentation does not currently define `open`, `close`, or `message sent` event contracts.
Do not depend on similarly named browser events unless ThriveDesk documents them here.
## Related [#related]
* [Initialization](/assistant/initialization)
* [Styling and CSS overrides](/assistant/styling)
# Identify users safely (/assistant/identify)
`Assistant('identify', user)` supplies a visitor name and email so Chat and Contact can skip or
prefill those questions.
```js
Assistant('ready', () => {
Assistant('identify', {
name: 'Jane Cooper',
email: 'jane@example.com'
});
});
```
## Security boundary [#security-boundary]
No JWT- or HMAC-based Assistant identity contract is publicly documented. Values passed from
browser JavaScript can be changed by the visitor. Do not use `identify` to authorize access to
account data, invoices, orders, or private conversations.
Use your own authenticated backend for sensitive data. When the Assistant or a SmartApp calls that
backend, enforce the application session there and return only data the current user may access.
Never embed API keys, signing secrets, or unrestricted bearer tokens in the browser.
## Related [#related]
* [Custom customer data](/assistant/custom-data)
* [SmartApp authentication](/smartapp/authentication)
* [Assistant methods](/assistant/methods)
# Initialization and ready callback (/assistant/initialization)
Initialization connects the global `Assistant` queue to one configured Assistant. Calls that depend
on rendered UI should run only after the ready callback fires.
## Standard initialization [#standard-initialization]
```js
Assistant('init', 'YOUR_ASSISTANT_ID');
Assistant('ready', () => {
Assistant('open');
});
```
Use standard initialization when the configured launcher should appear.
## Triggerless initialization [#triggerless-initialization]
```js
Assistant('trigger-less-init', 'YOUR_ASSISTANT_ID');
Assistant('ready', () => {
document.querySelector('#support').addEventListener('click', () => {
Assistant('open');
});
});
```
`trigger-less-init` initializes without the normal launcher. The separate `triggerLess` command can
also hide the launcher after standard initialization.
## Errors [#errors]
* If `Assistant` is undefined, the installation snippet has not executed or was blocked.
* If ready never fires, verify the Assistant ID, browser console, network requests, and CSP.
* Do not initialize the same Assistant repeatedly during client-side route changes.
## Related [#related]
* [Events and lifecycle](/assistant/events)
* [Content Security Policy](/assistant/csp)
* [Troubleshooting](/assistant/troubleshooting)
# Assistant methods reference (/assistant/methods)
Call Assistant methods after installation, and use the `ready` callback for anything that depends on
the initialized widget.
| Method | Purpose | Prerequisite |
| --------------------------------------------- | --------------------------------------- | --------------------- |
| `Assistant('init', assistantId)` | Load an Assistant with its launcher. | Valid Assistant ID |
| `Assistant('trigger-less-init', assistantId)` | Load without the launcher. | Valid Assistant ID |
| `Assistant('triggerLess')` | Hide or disable the launcher. | Initialized Assistant |
| `Assistant('open')` | Open the Assistant. | Ready Assistant |
| `Assistant('close')` | Close the Assistant. | Ready Assistant |
| `Assistant('toggle')` | Toggle its open state. | Ready Assistant |
| `Assistant('chat')` | Open Chat. | Chat enabled |
| `Assistant('contact', options)` | Open Contact and optionally prefill it. | Contact enabled |
| `Assistant('order-status')` | Open Order Status. | Order Status enabled |
| `Assistant('identify', user)` | Prefill a visitor's name and email. | Ready Assistant |
| `Assistant('article', article)` | Open a Knowledge Base article. | Article ID |
| `Assistant.clearSession()` | Clear local chat/session state. | Initialized Assistant |
| `Assistant('ready', callback)` | Run code after initialization. | Installation snippet |
## Open contact with defaults [#open-contact-with-defaults]
```js
Assistant('ready', () => {
Assistant('contact', {
subject: 'Invoice INV-1042',
body: 'I need help understanding this charge.'
});
});
```
## Open an article [#open-an-article]
```js
Assistant('article', 'ARTICLE_ID');
Assistant('article', {
articleId: 'ARTICLE_ID',
mode: 'sidebar'
});
```
Find the article ID by opening the article editor in ThriveDesk.
## Clear the session on logout [#clear-the-session-on-logout]
```js
async function logout() {
Assistant.clearSession();
await endApplicationSession();
}
```
Clearing the Assistant session removes local chat history and conversation context for that browser.
## Related [#related]
* [Initialization](/assistant/initialization)
* [Identify users](/assistant/identify)
* [Original help-center article](https://help.thrivedesk.com/en/javascript-api)
# Assistant SDK overview (/assistant/overview)
The Assistant SDK is the browser integration surface for the ThriveDesk widget. Use it to initialize
an Assistant, open a specific screen, prefill contact details, display Knowledge Base articles, and
coordinate widget behavior with your application.
## Prerequisites [#prerequisites]
* A configured Assistant in **Settings → Channel → Assistant**.
* The Assistant ID and installation snippet from its **Installation** tab.
* Permission to add JavaScript to your website or tag manager.
## Install the Assistant [#install-the-assistant]
Copy the installation snippet shown by ThriveDesk and place it before your closing `` tag.
The snippet is the source of truth for the current script URL and Assistant ID; do not copy those
values from another workspace.
After the snippet loads, register work that depends on the widget inside the ready callback:
```html