Quickstart

This page 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

Hit GET /v1/me with the bearer token. The response includes the organization, the current user, the inbox IDs you have access to, and your 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 (no pagination). For a full, paginated list use GET /v1/inboxes/{inbox_id} (see Pagination & 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 on the conversation. 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 one the request fails with 404). The body sets 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"}'