# Fila do número

Fonte: https://apiwpp.com/docs/api/mensagens/fila-do-numero
Seção: Mensagens
Atualizado em: 2026-09-28

`GET /connections/{id}/queue`

Mostra a fila de envio do número e o uso dos limites de envio: quantas mensagens esperam, os limites por minuto, hora e dia, o limite de destinatários novos a cada 24 horas e o aquecimento de um número conectado há menos de 14 dias. Escopo necessário: `connections:read`.

## Cabeçalhos

| Nome | Obrigatório | Descrição |
| --- | --- | --- |
| `Authorization` | sim | `Bearer <chave de API>`; ou envie a chave em `X-Api-Key`. |

## Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string · uuid` | sim | Identificador da conexão (o número). |

## Exemplo de requisição

### cURL

```bash
curl https://api.apiwpp.com/connections/$CONNECTION_ID/queue \
  -H "Authorization: Bearer $API_KEY"
```

### Node.js

```javascript
const res = await fetch(`https://api.apiwpp.com/connections/${connectionId}/queue`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
})
const data = await res.json()
```

### PHP

```php
$response = Http::withToken($apiKey)
    ->get("https://api.apiwpp.com/connections/{$connectionId}/queue");
```

### Python

```python
import requests

response = requests.get(
    f"https://api.apiwpp.com/connections/{connection_id}/queue",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
```

## Respostas

| Código | Erro | Descrição |
| --- | --- | --- |
| 200 |  | A fila e os limites de envio do número. |
| 400 | `FST_ERR_VALIDATION` | `id` não é um UUID. |
| 401 |  | Sem chave de API, ou com uma chave inválida (desconhecida, revogada ou expirada). |
| 403 |  | A chave de API não tem o escopo `connections:read`; a mensagem do erro cita o escopo que falta. |
| 404 |  | A conexão não existe ou não é de quem chama (o recurso de outra pessoa responde igual a um que não existe). |
| 429 |  | Requisições demais deste IP de origem, ou autenticações com falha demais: espere Retry-After segundos. Cabeçalhos: `Retry-After`. |
| 503 |  | A instância do gateway que roda a conexão está mudando (um reinício, um failover) ou não responde: espere Retry-After segundos e tente de novo. Cabeçalhos: `Retry-After`. |

### 200 OK

```json
{
  "pending": 1,
  "scheduled": 2,
  "limits": {
    "perMinute": 3,
    "perHour": 60,
    "perDay": 200,
    "newRecipientsPerDay": 100
  },
  "usage": {
    "minute": 1,
    "hour": 12,
    "day": 40,
    "newRecipients": 7
  },
  "warmup": {
    "createdAt": 1789646400000,
    "messagesSent": 40,
    "isInWarmup": false,
    "endsAt": 1790856000000
  }
}
```

## Detalhes

Na resposta: `pending` conta as mensagens cujo horário de envio já chegou e que esperam a vez; `scheduled`, as agendadas para depois pelo ritmo do número. `limits` são os limites em vigor agora (menores durante o aquecimento): `perMinute`, `perHour`, `perDay` e `newRecipientsPerDay` (`null` quando não há limite de destinatários novos). `usage` é o que já foi usado em cada janela, com `newRecipients` contando os destinatários novos das últimas 24 horas.

`warmup` descreve o aquecimento: `createdAt` é quando o número foi conectado (unix em milissegundos), `endsAt` quando o aquecimento termina (14 dias depois), `isInWarmup` diz se ele ainda está em curso e `messagesSent` quantas mensagens o número já enviou.

Funciona mesmo com a organização sem pagamento em dia: só consulta, não usa o WhatsApp.

Guia: [Limites de envio](https://apiwpp.com/docs/guias/limites-de-envio).
