TidySupport logo
TidySupport logo

  1. Home

    2. /

  2. Docs

    3. /

  3. API Reference

    4. /

  4. Conversations

Conversations API

Conversations are support threads between a contact and your team. Each conversation has a status, is associated with a contact, and contains messages. Use these endpoints to list, filter, create, and manage conversations in your inbox.

Conversation Status

Every conversation has one of the following statuses:

  • OPEN - Active conversation requiring attention
  • CLOSED - Resolved conversation
  • ARCHIVED - Archived conversation (hidden from default inbox view)

Endpoints

GET/v1/workspaces/{workspaceId}/support/inbox/conversations

Lists conversations in your support inbox with filtering and pagination support.

Request

curl "https://api.tidysupport.com/v1/workspaces/wrk_abc123/support/inbox/conversations?status=OPEN&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "conversations": {
    "items": [
      {
        "id": "thd_xyz789",
        "status": "OPEN",
        "source": "EMAIL",
        "subject": "Billing question",
        "isUnread": true,
        "lastMessageAt": "2025-03-12T14:30:00Z",
        "lastMessagePreview": "Hi, I have a question about my invoice...",
        "assignedToId": "agt_abc123",
        "channelId": "chn_def456",
        "contact": {
          "id": "ctc_B7OSYsnTUVwBPOGrgYTjvSGS",
          "email": "jane@example.com",
          "name": "Jane Doe",
          "avatarUrl": null
        }
      }
    ],
    "hasMore": true
  }
}

POST/v1/workspaces/{workspaceId}/support/inbox/conversations

Creates a new outbound conversation. This sends an email to the specified address and creates the conversation thread in your inbox.

Request

curl -X POST "https://api.tidysupport.com/v1/workspaces/wrk_abc123/support/inbox/conversations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "name": "Jane Doe",
    "subject": "Following up on your request",
    "contentText": "Hi Jane, I wanted to follow up on your recent support request..."
  }'

Response

{
  "conversation": {
    "id": "thd_new123"
  },
  "contact": {
    "id": "ctc_B7OSYsnTUVwBPOGrgYTjvSGS"
  },
  "message": {
    "id": "msg_abc456",
    "contentPreview": "Hi Jane, I wanted to follow up...",
    "status": "SENT"
  }
}

PUT/v1/workspaces/{workspaceId}/support/inbox/conversations/{conversationId}/status

Updates the status of a conversation. Use this to close resolved conversations or reopen them.

Request

curl -X PUT "https://api.tidysupport.com/v1/workspaces/wrk_abc123/support/inbox/conversations/thd_xyz789/status" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "CLOSED"
  }'

Response

{
  "conversation": {
    "id": "thd_xyz789",
    "status": "CLOSED"
  }
}

PUT/v1/workspaces/{workspaceId}/support/inbox/conversations/{conversationId}/assign

Reassigns a conversation to a specific agent. Pass null as the agentId to unassign the conversation.

Request

curl -X PUT "https://api.tidysupport.com/v1/workspaces/wrk_abc123/support/inbox/conversations/thd_xyz789/assign" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agt_abc123"
  }'

Response

{
  "conversation": {
    "id": "thd_xyz789",
    "assignedToAgentId": "agt_abc123"
  }
}

GET/v1/workspaces/{workspaceId}/support/inbox/customers/{contactId}/conversations

Lists all conversations for a specific contact. Useful for viewing a customer's full support history.

Request

curl "https://api.tidysupport.com/v1/workspaces/wrk_abc123/support/inbox/customers/ctc_B7OSYsnTUVwBPOGrgYTjvSGS/conversations" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "conversations": {
    "items": [
      {
        "id": "thd_xyz789",
        "status": "OPEN",
        "source": "EMAIL",
        "subject": "Billing question",
        "lastMessageAt": "2025-03-12T14:30:00Z",
        "lastMessagePreview": "Hi, I have a question...",
        "assignedToId": "agt_abc123"
      },
      {
        "id": "thd_abc456",
        "status": "CLOSED",
        "source": "CHAT",
        "subject": null,
        "lastMessageAt": "2025-03-10T09:15:00Z",
        "lastMessagePreview": "Thanks for your help!",
        "assignedToId": null
      }
    ],
    "hasMore": false
  }
}

Conversation Object

idstring
Unique identifier (prefixed with thd_)
statusstring
OPEN, CLOSED, or ARCHIVED
sourcestring
Channel the conversation originated from (EMAIL, CHAT, FORM, API)
subjectstring | null
Subject line (typically from email conversations)
isUnreadboolean
Whether the conversation has unread messages
lastMessageAtstring
ISO 8601 timestamp of the last message
lastMessagePreviewstring
Text preview of the last message
assignedToIdstring | null
ID of the assigned agent, or null if unassigned
channelIdstring | null
ID of the email channel
contactobject
The associated contact (id, email, name, avatarUrl)

Error Handling

404 - Not Found

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Conversation not found."
}

400 - Invalid Status

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid status. Must be one of: OPEN, CLOSED, ARCHIVED."
}