Quickstart

Create an access token, inspect your account, retrieve conversations, and send a reply.

This guide walks through a complete session with the ThriveDesk Public API: create an access token, fetch the current user, list your open conversations, then draft and send a reply. The examples use curl so they run from any shell.

1. Create an API key

In the ThriveDesk app, open Settings → Integrations → API Keys and create a new key. Give it a name, copy the plaintext key when it is shown, and store it in a secrets manager. It will not be displayed again.

export TOKEN="eyJ0eXAiOiJKV1Qi..."

Treat the key as a secret. Keys expire one year after creation; rotate them by revoking the old key from the same screen and issuing a new one. They are the only publicly documented authentication method at this time, so integrations must never collect ThriveDesk passwords on a user's behalf.

2. Confirm who you are

Call GET /v1/me with the bearer token. The response includes the organization, current user, accessible inbox IDs, and unread badge count.

curl https://api.thrivedesk.com/v1/me \
  -H "Authorization: Bearer $TOKEN"

3. List your open conversations

GET /v1/conversations/mine returns up to five of the conversations most recently assigned to the current user, without pagination. For a full, paginated list use GET /v1/inboxes/{inbox_id}. See Pagination and rate limits.

curl https://api.thrivedesk.com/v1/conversations/mine \
  -H "Authorization: Bearer $TOKEN"

4. Read a conversation's thread

GET /v1/conversation/{conversation_id} returns the conversation metadata plus its thread events. Events include incoming messages, outgoing replies, notes, drafts, scheduled replies, and system events.

5. Draft a reply

POST /v1/conversation/{conversation_id}/draft creates or updates the authenticated user's reply draft. There is one draft per user per conversation; posting again overwrites it.

curl -X POST "https://api.thrivedesk.com/v1/conversation/$CONV_ID/draft" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "<p>Thanks for reaching out - fixed in v2.1.</p>"}'

6. Send it

POST /v1/conversation/{conversation_id}/reply dispatches your current draft. Without a draft, the request fails with 404. The body controls what happens to the conversation after sending; status is required.

curl -X POST "https://api.thrivedesk.com/v1/conversation/$CONV_ID/reply" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "Closed"}'