> ## Documentation Index > Fetch the complete documentation index at: https://developer.zapsterapi.com/llms.txt > Use this file to discover all available pages before exploring further. # Listar Mensagens > Lista todas as mensagens (imediatas e agendadas) dentro de um período. Retorna informações de status, entrega e leitura de cada mensagem. Usa paginação cursor-based para navegar entre páginas de resultados. O período máximo por consulta é de 90 dias. O quão longe no passado você pode consultar depende do seu plano (retenção do histórico). Lista todas as mensagens enviadas e agendadas dentro de um período. Retorna informações de status, entrega e leitura de cada mensagem. ## Parâmetros obrigatórios Os campos `from` e `to` definem o período da consulta. O período máximo é de 90 dias por requisição. O quão longe no passado você pode consultar depende do seu plano: | Plano | Retenção do histórico | | ---------- | --------------------- | | Essential | 24 horas | | Pro | 30 dias | | Enterprise | 180 dias | ## Filtros disponíveis Você pode combinar qualquer filtro na mesma requisição: | Filtro | Descrição | Exemplo | | ----------------- | ------------------------------ | -------------------------- | | `status` | Filtrar por status da mensagem | `status=scheduled` | | `instance_id` | Filtrar por instância | `instance_id=inst_xyz` | | `recipient` | Filtrar por destinatário | `recipient=5511999999999` | | `message_id` | Buscar pelo ID do WhatsApp | `message_id=wamid.HBgM...` | | `connection_type` | Filtrar por tipo de conexão | `connection_type=waba` | ## Paginação A listagem usa paginação cursor-based. Cada resposta inclui um objeto `meta` com: * `has_more`: indica se existem mais resultados * `next_cursor`: valor para passar no parâmetro `after` da próxima requisição * `limit`: quantidade de itens por página Para navegar entre páginas: 1. Faça a primeira requisição sem o parâmetro `after` 2. Se `has_more` for `true`, pegue o valor de `next_cursor` 3. Faça a próxima requisição com `after=` 4. Repita até `has_more` ser `false` O padrão é 20 itens por página. Você pode ajustar com o parâmetro `limit` (mínimo 1, máximo 100). ## Sobre o campo errors Quando uma mensagem falha (`status=failed`), o campo `errors` contém os detalhes do problema. Para instâncias WABA, inclui o código de erro da Meta e um link para a documentação. Erros comuns: | Código | Descrição | | ------ | ------------------------------------------------- | | 131047 | Janela de 24 horas expirada (precisa de template) | | 132000 | Template não encontrado ou parâmetros incorretos | | 132001 | Template não existe na tradução informada | ## OpenAPI ````yaml GET /wa/messages openapi: 3.1.0 info: title: Zapster API description: '' version: 1.0.0 servers: - url: https://api.zapsterapi.com/v1 description: Produção security: [] tags: [] paths: /wa/messages: get: tags: - Mensagens summary: Listar mensagens description: | Lista todas as mensagens (imediatas e agendadas) dentro de um período. Retorna informações de status, entrega e leitura de cada mensagem. Usa paginação cursor-based para navegar entre páginas de resultados. O período máximo por consulta é de 90 dias. O quão longe no passado você pode consultar depende do seu plano (retenção do histórico). parameters: - name: from in: query required: true schema: type: string format: date-time description: Início do período no formato ISO 8601 example: '2026-03-01T00:00:00Z' - name: to in: query required: true schema: type: string format: date-time description: Fim do período no formato ISO 8601 example: '2026-03-31T23:59:59Z' - name: instance_id in: query required: false schema: type: string description: Filtrar por ID da instância example: inst_xyz - name: status in: query required: false schema: type: string enum: - pending - scheduled - sent - failed - canceled description: Filtrar por status da mensagem - name: recipient in: query required: false schema: type: string description: Filtrar por destinatário (número de telefone) example: '5511999999999' - name: message_id in: query required: false schema: type: string description: Buscar pelo ID do WhatsApp (wamid) example: wamid.HBgM... - name: connection_type in: query required: false schema: type: string enum: - waba - unofficial description: Filtrar por tipo de conexão (oficial ou não oficial) - name: after in: query required: false schema: type: string format: date-time description: >- Cursor para a próxima página (valor de `next_cursor` da resposta anterior) - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 20 description: Quantidade de itens por página (1 a 100, padrão 20) responses: '200': description: Lista de mensagens com paginação content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/ScheduledMessage' meta: type: object properties: next_cursor: type: string nullable: true description: >- Cursor para a próxima página. Null quando não há mais resultados. example: '2026-03-28T09:00:00.000Z' has_more: type: boolean description: Indica se existem mais resultados além desta página example: true limit: type: integer description: Quantidade de itens retornados por página example: 20 '422': description: Erro de validação (período inválido ou retenção excedida) content: application/json: schema: type: object properties: code: type: string example: messages_retention_exceeded message: type: string example: >- Your current plan allows message history up to 24h. Upgrade your plan for longer retention. security: - bearer: [] components: schemas: ScheduledMessage: type: object description: Objeto de mensagem retornado na listagem properties: id: type: string description: Identificador único da mensagem example: msg_k7m2nxp9q4 instance_id: type: string description: ID da instância que enviou a mensagem example: inst_xyz recipient: type: string description: Número do destinatário example: '5511999999999' status: type: string enum: - pending - scheduled - sent - failed - canceled description: | Status atual da mensagem: - `pending`: mensagem imediata sendo processada - `scheduled`: agendada, aguardando o horário de envio - `sent`: enviada com sucesso - `failed`: falha no envio - `canceled`: cancelada pelo usuário example: sent connection_type: type: string enum: - waba - unofficial description: Tipo de conexão da instância (oficial ou não oficial) example: waba send_at: type: string format: date-time nullable: true description: Data e hora de envio agendado (null para mensagens imediatas) example: '2026-03-30T12:00:00.000Z' message_id: type: string nullable: true description: ID da mensagem no WhatsApp (wamid). Preenchido após o envio. example: wamid.HBgMNTU4... errors: type: array nullable: true description: Detalhes do erro quando status é `failed` items: type: object properties: code: type: integer description: Código de erro (da Meta, quando aplicável) example: 131047 title: type: string description: Título do erro example: Re-engagement message details: type: string description: Descrição detalhada do problema example: >- Message failed to send because more than 24 hours have passed since the customer last replied. href: type: string description: Link para documentação do erro example: >- https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/ created_at: type: string format: date-time description: Data e hora de criação da mensagem example: '2026-03-28T10:30:00.000Z' sent_at: type: string format: date-time nullable: true description: Data e hora em que a mensagem foi enviada example: '2026-03-28T10:30:01.000Z' delivered_at: type: string format: date-time nullable: true description: Data e hora em que o WhatsApp confirmou a entrega example: '2026-03-28T10:30:05.000Z' read_at: type: string format: date-time nullable: true description: Data e hora em que o destinatário leu a mensagem example: '2026-03-28T10:32:00.000Z' canceled_at: type: string format: date-time nullable: true description: Data e hora do cancelamento (quando aplicável) example: null securitySchemes: bearer: type: http scheme: bearer ````