GET /api/v1/chat/history — retrieve messages

Use this endpoint to retrieve the message history for a conversation between you and another user. The response is paginated and sorted oldest-first, so page 1 contains the earliest messages in the conversation. Each message object includes sender information, making it straightforward to render a full conversation thread.

Endpoint

GET /api/v1/chat/history

Authentication

Bearer token required. See Authentication.

Query parameters

handymanIdstringquery

ID of the handyman in the conversation. Use this when you are a partner or admin retrieving history with a handyman.

partnerIdstringquery

ID of the partner in the conversation. Use this when you are a handyman or admin retrieving history with a partner.

adminIdstringquery

ID of the admin in the conversation. Use this when you are a partner or handyman retrieving history with an admin.

pagenumberquerydefault: 1

Page number to retrieve. Pagination is 1-indexed — page 1 returns the oldest messages.

limitnumberquerydefault: 50

Number of messages to return per page.

Note

Exactly one of handymanId, partnerId, or adminId is required. These identify the other party in the conversation.

Example

curl "https://<your-portal-domain>/api/v1/chat/history?partnerId=partner_abc123&page=1&limit=50" \
  -H "Authorization: Bearer <your-token>"

Success response

Returns 200 OK. The data object contains the full messages array, the room identifier, and a pagination object.

messagesobject[]

Array of message objects, ordered oldest first.

message properties

idstring

Unique identifier for the message.

messagestring

Text content of the message. null for image messages.

messageTypestring

"text" or "image".

imageUrlstring

URL of the image for image messages. null for text messages.

imageSizestring

JSON-encoded string with fileSize and mimeType for image messages. null for text messages.

createdAtstring

ISO 8601 timestamp of when the message was sent.

senderIdstring

ID of the user who sent the message.

senderNamestring

Display name of the sender.

senderRolestring

Role of the sender: "partner", "handyman", or "admin".

roomIdstring

Identifier for the chat room containing these messages.

paginationobject

Pagination metadata for the result set.

pagination properties

pagenumber

The current page number returned.

limitnumber

The number of messages per page.

totalnumber

Total number of messages in the conversation.

hasNextboolean

true if there are more pages of messages after this one.

{
  "data": {
    "messages": [
      {
        "id": "msg_123",
        "message": "Welcome to Heyzack! How can we help you today?",
        "messageType": "text",
        "imageUrl": null,
        "imageSize": null,
        "createdAt": "2024-01-16T10:00:00.000Z",
        "senderId": "admin_xyz789",
        "senderName": "Heyzack Admin",
        "senderRole": "admin"
      },
      {
        "id": "msg_124",
        "message": "I need help with my account settings.",
        "messageType": "text",
        "imageUrl": null,
        "imageSize": null,
        "createdAt": "2024-01-16T10:05:00.000Z",
        "senderId": "partner_abc123",
        "senderName": "John Doe",
        "senderRole": "partner"
      },
      {
        "id": "msg_125",
        "message": null,
        "messageType": "image",
        "imageUrl": "https://storage.example.com/chat/image.jpg",
        "imageSize": "{\"fileSize\":123456,\"mimeType\":\"image/jpeg\"}",
        "createdAt": "2024-01-16T10:10:00.000Z",
        "senderId": "admin_xyz789",
        "senderName": "Heyzack Admin",
        "senderRole": "admin"
      }
    ],
    "roomId": "room_admin_partner_abc123",
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 3,
      "hasNext": false
    }
  }
}

Pagination

Responses include a pagination object with page, limit, total, and hasNext. To load older messages use a higher page number. When hasNext is false, you have reached the most recent page of messages.

Messages are always returned in chronological order — oldest first within each page.

Note

When a partner or handyman opens a chat with admin for the first time, a welcome message ("Welcome to Heyzack! How can we help you today?") will appear as the first entry in the history. This message is sent automatically from the admin account and does not require any action from you.