Skip to content

docs(queue): deprecate GET /queue, add migration note and pagination limits #124

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
paolamayuri wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs(queue): deprecate GET /queue, add migration note and pagination limits #124

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
89ced1e
docs(queue): mark GET /queue as legacy and clarify pagination behavior
paolamayuri-dotcom Apr 1, 2026
549b5a9
docs(queue): deprecate GET /queue, add migration note and pagination …
paolamayuri Apr 2, 2026
19f4d62
docs(queue): add POST /queue endpoint and pagination docs
paolamayuri Apr 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 27 additions & 14 deletions docs/queue/get-queue.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,15 @@
---
id: get-queue
title: Fila
title: Fila (Antiga)
---

:::danger Endpoint obsoleto e em descontinuação
Este endpoint está **obsoleto**, pois o modelo de paginação foi atualizado para um formato baseado em **cursor (pagingState)**.
**Descontinuação programada:** Este endpoint será removido em **30/04**.
Recomendamos que todas as integrações sejam migradas para o novo endpoint [**POST /queue**](./post-queue), que utiliza o novo modelo de paginação.

:::

## Método

#### /queue
Expand All @@ -14,6 +21,7 @@ title: Fila
| Key | Value |
| :------------: | :-----------------: |
| Client-Token | **[TOKEN DE SEGURANÇA DA CONTA](../security/client-token)** |

---

## Conceituação
Expand All @@ -28,17 +36,24 @@ Este método é responsável por retornar todas mensagens que estão em sua fila

| Atributos | Tipo | Descrição |
| :-------- | :---: | :-------- |
| page | integer | Utilizado para paginação você de informar aqui a pagina de mensagens que quer buscar |
| pageSize | integer | Especifica o tamanho do retorno de mensagens por pagina |
| page | integer | **Não possui mais efeito** |
| pageSize | integer | Especifica o tamanho do retorno de mensagens por página |

### Opcionais

| Atributos | Tipo | Descrição |
| :-------- | :--: | :-------- |
| Atributos | Tipo | Descrição |
| :-------- | :--: | :-------- |
| count | string | Atributo utilizado para retornar o número de mensagens na fila |

---

## Regras de Paginação

- O limite máximo de mensagens por página é **30**
- O valor padrão (quando não informado) é **20**

---

## Request Params

#### URL exemplo
Expand All @@ -47,11 +62,10 @@ Método

`GET` https://api.z-api.io/instances/SUA_INSTANCIA/token/SEU_TOKEN/queue?page=1&pageSize=100

ou
ou

`GET` https://api.z-api.io/instances/SUA_INSTANCIA/token/SEU_TOKEN/queue/count


---

## Response
Expand All @@ -60,7 +74,7 @@ Método

| Atributos | Tipo | Descrição |
| :-------- | :----------- | :------------------------------ |
| messages | array string | Array com as menssagens da fila |
| messages | array string | Array com as mensagens da fila |

Array Messages

Expand All @@ -69,13 +83,13 @@ Array Messages
| _id | string | ID da mensagem no Z-API |
| DelayMessage | string | Tempo em segundos entre o envio das mensagens |
| Message | string | Texto da Mensagem |
| IsTrial | boolean | Indica se a instância está utilizando trial |
| IsTrial | boolean | Indica se a instância está utilizando trial |
| InstanceId | string | ID da instância |
| Phone | string | Número do destinatário |
| ZaapId | string | ID da mensagem no Z-API |
| DelayTyping | string | Duração do indicador do chat "digitando..." |
| DelayTyping | string | Duração do indicador do chat "digitando..." |
| MessageId | string | ID da mensagem |
| Created | timetamp | Data da mensagem |
| Created | timestamp | Data da mensagem |

Exemplo

Expand All @@ -92,8 +106,7 @@ Exemplo
"ZaapId": "39BB1684570F00E91090F6BBC7EE7646",
"DelayTyping": 0,
"MessageId": "7AD29EAA5EF34C301F0B",
"Created": 1624977905648,

"Created": 1624977905648
},
{
"_id": "39BB1684570F00E91090F6BBC7EE7646",
Expand All @@ -105,7 +118,7 @@ Exemplo
"ZaapId": "39BB1684570F00E91090F6BBC7EE7646",
"DelayTyping": 5,
"MessageId": "7AD29EAA5EF34C301F0B",
"Created": 1624977906907,
"Created": 1624977906907
}
]
}
Expand Down
124 changes: 124 additions & 0 deletions docs/queue/post-queue.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
---
id: post-queue
title: Fila
---

## Método

#### /queue

`POST` https://api.z-api.io/instances/SUA_INSTANCIA/token/SEU_TOKEN/queue

### Header

| Key | Value |
| :------------: | :-----------------: |
| Client-Token | **[TOKEN DE SEGURANÇA DA CONTA](../security/client-token)** |

---

## Conceituação

Este método é responsável por retornar mensagens da fila aguardando processamento.

---

## Body

### Opcionais

| Atributos | Tipo | Descrição |
| :---------- | :--: | :-------- |
| pageSize | integer | Quantidade de mensagens retornadas por requisição. O valor padrão é **20** e o limite máximo é **30** |
| pagingState | string | Cursor da página. Quando não informado, retorna a primeira página |

---

## Request Body

### Exemplo

**Para buscar a primeira página:**

```json
{}
```

**Para buscar a próxima página:**

```json
{
"pageSize": 20,
"pagingState": "eyJidWNrZXQiOjI5MzQsInBhZ2VTdGF0ZSI6IjAw..."
}
```

---

## Response

### 200

| Atributos | Tipo | Descrição |
| :---------- | :------ | :-------- |
| messages | array | Lista de mensagens da fila |
| pagingState | string | Cursor para próxima página |
| hasMore | boolean | Indica se existem mais páginas |

---

### Array Messages

| Atributos | Tipo | Descrição |
| :----------- | :-------- | :-------- |
| _id | string | ID da mensagem no Z-API |
| DelayMessage | integer | Tempo entre envios |
| Message | string | Texto da mensagem |
| InstanceId | string | ID da instância |
| Phone | string | Número ou grupo |
| ZaapId | string | ID da mensagem |
| DelayTyping | integer | Tempo do "digitando..." |
| MessageId | string | ID da mensagem |
| Created | timestamp | Data em epoch |
| CreatedAt | string | Data formatada |
| Beta | boolean | Indica uso de beta |
| IsTrial | boolean | Indica trial |

---

## Exemplo

```json
{
"messages": [
{
"DelayMessage": -1,
"Message": "Mensagem teste",
"InstanceId": "3E98XXXXXXXXXXXXXXXXXXXF5DDF",
"CreatedAt": "2026-03-31T14:40:31.776+00:00",
"ZaapId": "019D44XXXXXXXXXXXXXXXXX68DA6",
"DelayTyping": 0,
"Created": 1774968031776,
"Beta": false,
"IsTrial": false,
"Phone": "120XXXXXXXXXXX305-group",
"_id": "019D44XXXXXXXXXXXXXXXXX68DA6",
"MessageId": "ECFXXXXXXXXXXXXXX39"
}
],
"pagingState": "eyJi...",
"hasMore": true
}
```

---

## Paginação

- Caso não envie `pagingState`, a primeira página será retornada automaticamente
- Caso não informe `pageSize`, o valor padrão de **20 mensagens** será utilizado
- O limite máximo por requisição é de **30 mensagens**
- Utilize o `pagingState` retornado para buscar as próximas páginas
- Quando `hasMore` for `false`, não existem mais mensagens disponíveis

---
100 changes: 63 additions & 37 deletions i18n/en/docusaurus-plugin-content-docs/current/queue/get-queue.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,16 @@
---
id: get-queue
title: Queue
title: Queue (Legacy)
---

:::danger Deprecated endpoint

This endpoint is **deprecated**, as the pagination model has been updated to a **cursor-based approach (pagingState)**.
**Scheduled deprecation:** This endpoint will be discontinued on **04/30**.
We strongly recommend migrating all integrations to the new endpoint [**POST /queue**](./post-queue), which uses the updated pagination model.

:::

## Method

#### /queue
Expand All @@ -19,37 +27,43 @@ title: Queue

## Concept

This method is responsible for returning all messages that are in your queue waiting to be processed.
This method returns all messages currently in the queue waiting to be processed.

---

## Attributes
## Attributes

### Required
### Required

| Attributes | Type | Description |
| :-------- | :---: | :-------- |
| page | integer | Used for pagination, you need to inform here the message page you want to retrieve |
| pageSize | integer | Specify the size of the message return per page |
| :--------- | :---: | :---------- |
| page | integer | **No longer has any effect** |
| pageSize | integer | Defines the number of messages returned per page |

### Optional

### Optionals
| Attributes | Type | Description |
| :--------- | :--: | :---------- |
| count | string | Used to return the number of messages in the queue |

| Attributes | Type | Description |
| :-------- | :--: | :-------- |
| | | |
---

## Pagination Rules

- The maximum number of messages per page is **30**
- The default value (when not specified) is **20**

---

## Request Params

#### URL example
#### Example URL

Method
Method

`GET` https://api.z-api.io/instances/YOUR_INSTANCE/token/YOUR_TOKEN/queue?page=1&pageSize=100

or
or

`GET` https://api.z-api.io/instances/YOUR_INSTANCE/token/YOUR_TOKEN/queue/count

Expand All @@ -59,41 +73,53 @@ Method

### 200

| Attributes | Type | Description |
| :-------- | :----------- | :------------------------------ |
| size | string | Number of messages in queue |
| messages | array string | Array with queue messages|
| Attributes | Type | Description |
| :--------- | :----------- | :------------------------------ |
| messages | array string | Array containing queue messages |

Messages Array
Messages Array

| Attributes | Type | Description |
| :-------- | :------- | :-------------------------- |
| size | string | Number of messages in queue |
| Message | string | Text message |
| Phone | string | Recipients phone |
| ZaapId | string | Z-API message ID |
| Created | timetamp | Messages date |
| MessageId | string | Message ID |
| Attributes | Type | Description |
| :----------- | :------- | :---------- |
| _id | string | Message ID in Z-API |
| DelayMessage | string | Delay in seconds between message sends |
| Message | string | Message text |
| IsTrial | boolean | Indicates if the instance is using trial mode |
| InstanceId | string | Instance ID |
| Phone | string | Recipient phone number |
| ZaapId | string | Message ID in Z-API |
| DelayTyping | string | Duration of the "typing..." indicator |
| MessageId | string | Message ID |
| Created | timestamp | Message timestamp |

Example
Example

```json
{
"size": 2,
"messages": [
[
{
"Message": "Mensagem da fila 1",
"_id": "39BB1684570F00E91090F6BBC7EE7646",
"DelayMessage": -1,
"Message": "Queue message 1",
"IsTrial": false,
"InstanceId": "3A5D07856DC26A1C9E2E08E691E63271",
"Phone": "5511999999999",
"ZaapId": "39BB1684570F00E91090F6BBC7EE7646",
"Created": 1624977905648,
"MessageId": "7AD29EAA5EF34C301F0B"
"DelayTyping": 0,
"MessageId": "7AD29EAA5EF34C301F0B",
"Created": 1624977905648
},
{
"Message": "Mensagem da fila 2",
"_id": "39BB1684570F00E91090F6BBC7EE7646",
"DelayMessage": -1,
"Message": "Queue message 2",
"IsTrial": false,
"InstanceId": "3A5D07856DC26A1C9E2E08E691E63271",
"Phone": "5511999999999",
"ZaapId": "39BB1685172AB008542A7E0B862A54DF",
"Created": 1624977906907,
"MessageId": "517AEF0FDE834DADJJFC8"
"ZaapId": "39BB1684570F00E91090F6BBC7EE7646",
"DelayTyping": 5,
"MessageId": "7AD29EAA5EF34C301F0B",
"Created": 1624977906907
}
]
}
Expand Down
Loading