Message history

GET /v1/messages

Retrieve a channel's message history with pagination and filtering by contact.

URL

GET https://api.wazzabee.com/api-gateway/v1/messages?channelId=...&chatId=...&limit=50&offset=0

Headers

Authorization: Bearer YOUR_API_KEY

Query string parameters

Parameter	Type	Required	Default	Description
channelId	string (UUID)	✅ Yes	-	Channel ID. Get it via GET /v1/channels
chatId	string	No	-	Filter by contact: a phone number or a chat_id. If omitted, all messages of the channel are returned
limit	integer	No	50	Number of messages per page. Maximum: 200
offset	integer	No	0	Pagination offset (how many messages to skip)
campaignId	string	No	-	Only messages of the campaign with this label (campaignId from the send)

Request examples

All messages of a channel (the latest 50)

curl -X GET "https://api.wazzabee.com/api-gateway/v1/messages?channelId=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Messages of a specific contact

curl -X GET "https://api.wazzabee.com/api-gateway/v1/messages?channelId=550e8400-e29b-41d4-a716-446655440000&chatId=77001234567" \
  -H "Authorization: Bearer YOUR_API_KEY"

Pagination: the second page of 20 messages

curl -X GET "https://api.wazzabee.com/api-gateway/v1/messages?channelId=550e8400-e29b-41d4-a716-446655440000&limit=20&offset=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Successful response (200 OK)

{
  "success": true,
  "messages": [
    {
      "id": "msg-uuid-1",
      "conversationId": "conv-uuid-1",
      "contactId": "contact-uuid-1",
      "direction": "incoming",
      "type": "text",
      "text": "Hello, when will my order be ready?",
      "mediaUrl": null,
      "createdAt": "2026-03-12T10:30:00.000Z"
    },
    {
      "id": "msg-uuid-2",
      "conversationId": "conv-uuid-1",
      "contactId": "contact-uuid-1",
      "direction": "outgoing",
      "type": "text",
      "text": "Good afternoon! Your order will be ready tomorrow.",
      "mediaUrl": null,
      "createdAt": "2026-03-12T10:31:00.000Z"
    }
  ],
  "total": 156,
  "limit": 50,
  "offset": 0
}

Response fields

Field	Type	Description
messages	array	An array of messages, sorted from newest to oldest
messages[].id	string (UUID)	Unique message ID
messages[].conversationId	string (UUID)	ID of the conversation the message belongs to
messages[].contactId	string (UUID)	Contact ID
messages[].direction	string	incoming: inbound, outgoing: outbound
messages[].type	string	Message type: text, image, video, document, audio
messages[].text	string | null	Message text (null for media without a caption)
messages[].mediaUrl	string | null	URL of the media file (null for text messages)
messages[].createdAt	string (ISO 8601)	Date and time the message was created
messages[].queueId	string | null	Outgoing only: queueId from the send response
messages[].campaignId	string | null	Outgoing only: campaign label
messages[].status	string	Outgoing only: pending, sent, delivered, read, failed
messages[].sentAt, deliveredAt, readAt	string | null	Outgoing only: time sent, delivered and read
messages[].error	object | null	Undelivered only: {"code": 131026, "description": "..."}
total	integer	Total number of messages (for pagination)
limit	integer	Current page limit
offset	integer	Current offset

Pagination

Messages are sorted from newest to oldest (by createdAt DESC). Use offset and limit to page through them.

Filtering by chatId

If chatId is provided, the API looks up the contact by phone number or external_id and returns only that contact's messages. If no contact with such a chatId is found, an empty array is returned (not an error).

Possible errors

Code	Error	Reason
400	The channelId parameter is required	channelId is missing from the query string
403	The channel is not linked to this integration	The channel is not among those allowed for this API key
404	Channel not found or access denied	The channel does not exist or belongs to another user