TidySupport logo
TidySupport logo

  1. Home

    2. /

  2. Docs

    3. /

  3. API Reference

    4. /

  4. Messages

Messages API

Messages are individual communications within a conversation thread. They can be inbound (from a customer), outbound (from an agent), or internal notes visible only to your team. Use these endpoints to retrieve conversation history and send replies.

Message Types

Direction

  • INBOUND - Message from the customer
  • OUTBOUND - Message from your team
  • SYSTEM - Automated system message

Sender Type

  • CUSTOMER - Sent by the contact
  • AGENT - Sent by a support agent
  • SYSTEM - Generated by the system

Endpoints

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

Retrieves messages in a conversation along with the conversation details, contact information, and channel configuration. Messages are returned in chronological order.

Request

curl "https://api.tidysupport.com/v1/workspaces/wrk_abc123/support/inbox/conversations/thd_xyz789/messages?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "thread": {
    "conversation": {
      "id": "thd_xyz789",
      "status": "OPEN",
      "source": "EMAIL",
      "subject": "Billing question",
      "summary": "Customer has a question about their March invoice amount."
    },
    "contact": {
      "id": "ctc_B7OSYsnTUVwBPOGrgYTjvSGS",
      "email": "jane@example.com",
      "name": "Jane Doe"
    },
    "channel": {
      "id": "chn_def456",
      "name": "Support",
      "email": "support@yourcompany.com"
    },
    "messages": {
      "items": [
        {
          "id": "msg_001",
          "direction": "INBOUND",
          "senderType": "CUSTOMER",
          "contentText": "Hi, I have a question about my March invoice...",
          "contentHtml": "<p>Hi, I have a question about my March invoice...</p>",
          "contentPreview": "Hi, I have a question about my March invoice...",
          "status": "SENT",
          "attachments": [],
          "createdAt": "2025-03-12T14:00:00Z",
          "sentAt": "2025-03-12T14:00:00Z"
        },
        {
          "id": "msg_002",
          "direction": "OUTBOUND",
          "senderType": "AGENT",
          "contentText": "Hi Jane! I'd be happy to help with your invoice...",
          "contentHtml": "<p>Hi Jane! I'd be happy to help with your invoice...</p>",
          "contentPreview": "Hi Jane! I'd be happy to help with your invoice...",
          "status": "SENT",
          "attachments": [],
          "agentId": "agt_abc123",
          "createdAt": "2025-03-12T14:30:00Z",
          "sentAt": "2025-03-12T14:30:05Z"
        }
      ],
      "hasMore": false
    }
  }
}

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

Sends a new message in a conversation. You can send a reply to the customer or create an internal note visible only to your team.

Send a Reply

curl -X POST "https://api.tidysupport.com/v1/workspaces/wrk_abc123/support/inbox/conversations/thd_xyz789/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contentText": "Hi Jane! I checked your account and the charge is correct. Here is the breakdown...",
    "contentHtml": "<p>Hi Jane! I checked your account and the charge is correct. Here is the breakdown...</p>"
  }'

Send an Internal Note

curl -X POST "https://api.tidysupport.com/v1/workspaces/wrk_abc123/support/inbox/conversations/thd_xyz789/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contentText": "Checked the billing system - this customer is on the Pro plan. Invoice looks correct.",
    "isInternalNote": true
  }'

Response

{
  "message": {
    "id": "msg_new789",
    "direction": "OUTBOUND",
    "senderType": "AGENT",
    "contentText": "Hi Jane! I checked your account and the charge is correct...",
    "contentPreview": "Hi Jane! I checked your account and the charge is correct...",
    "status": "SENT",
    "attachments": [],
    "agentId": "agt_abc123",
    "createdAt": "2025-03-13T10:15:00Z",
    "sentAt": "2025-03-13T10:15:02Z"
  }
}

Message Object

idstring
Unique identifier (prefixed with msg_)
directionstring
INBOUND, OUTBOUND, or SYSTEM
senderTypestring
CUSTOMER, AGENT, or SYSTEM
contentTextstring
Plain text content of the message
contentHtmlstring | null
HTML content of the message
contentPreviewstring
Short text preview of the message
statusstring
SENT, FAILED, RETRYING, or PENDING
attachmentsarray
File attachments (each with id, name, mimeType, sizeBytes, url)
agentIdstring | null
ID of the agent who sent the message (for outbound messages)
createdAtstring
ISO 8601 timestamp when the message was created
sentAtstring | null
ISO 8601 timestamp when the message was delivered

Attachment Object

idstringrequired
Unique identifier for the attachment
namestringrequired
Original filename (e.g., "invoice.pdf")
mimeTypestringrequired
MIME type (e.g., "application/pdf", "image/png")
sizeBytesintegerrequired
File size in bytes
urlstring
Download URL for the attachment

Maximum payload size for sending messages with attachments is 10 MB.

Error Handling

404 - Conversation Not Found

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

400 - Missing Content

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Either contentText or contentHtml is required."
}