Skip to main content
POST
/
instances
/
{instanceId}
/
token
/
{token}
/
queue
Queue
curl --request POST \
  --url https://api.z-api.io/instances/{instanceId}/token/{token}/queue \
  --header 'Client-Token: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "pageSize": 123,
  "pagingState": "<string>"
}
'
{
  "messages": [
    {}
  ],
  "pagingState": "<string>",
  "hasMore": true
}

​
Overview

This method returns messages in the queue awaiting processing, with cursor-based pagination support. Unlike the GET endpoint, this one allows more efficient pagination using pagingState.

​
Attributes

​
Required

​
instanceId
string
required
Your instance ID. Available in the Z-API panel under Instances.
​
token
string
required
Your Z-API instance token.

​
Body (Optional)

​
pageSize
integer
Number of messages returned per request. Default: 20, max: 30.
​
pagingState
string
Pagination cursor. When not provided, returns the first page. Use the value returned in the response to fetch the next pages.

​
Request Body

First page: 
{}
Next pages: 
{
  "pageSize": 20,
  "pagingState": "eyJidWNrZXQiOjI5MzQsInBhZ2VTdGF0ZSI6IjAw..."
}

​
Response

​
200

​
messages
array
List of queue messages
​
pagingState
string
Cursor for the next page
​
hasMore
boolean
Indicates if more pages exist
{
  "messages": [
    {
      "_id": "019D44XXXXXXXXXXXXXXXXX68DA6",
      "DelayMessage": -1,
      "Message": "Test message",
      "InstanceId": "3E98XXXXXXXXXXXXXXXXXXXF5DDF",
      "Phone": "5511999999999",
      "ZaapId": "019D44XXXXXXXXXXXXXXXXX68DA6",
      "DelayTyping": 0,
      "MessageId": "ECFXXXXXXXXXXXXXX39",
      "Created": 1774968031776,
      "CreatedAt": "2026-03-31T14:40:31.776+00:00",
      "Beta": false,
      "IsTrial": false
    }
  ],
  "pagingState": "eyJi...",
  "hasMore": true
}

​
Pagination

  • If you don’t send pagingState, the first page will be returned automatically
  • If you don’t provide pageSize, the default value of 20 messages will be used
  • The maximum number of messages that can be returned per page is 30
  • Use the returned pagingState to fetch the next pages
  • When hasMore is false, there are no more messages available

​
405

Make sure you are correctly sending the method specification, that is, verify that you sent POST or GET as specified at the beginning of this topic.

​
415

If you receive a 415 error, make sure to add the “Content-Type” header to your request, which in most cases is “application/json”.