> ## Documentation Index > Fetch the complete documentation index at: https://help.wizebot.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Listar contatos > Contatos vinculados a um número de WhatsApp, do mais recente para o mais antigo. ## OpenAPI ````yaml /openapi.json get /whatsapp/contacts openapi: 3.1.0 info: title: API WizeBot version: 3.0.0 description: >- A API da WizeBot tem duas camadas sobre a **mesma base** `https://api.wizebot.com.br/v1`. **Contrato multicanal** — a camada neutra. Os mesmos endpoints falam com WhatsApp, com Telegram e com os canais que vierem depois. O canal não aparece na URL nem no corpo: ele vem da conta escolhida como remetente. Campos, códigos e mensagens em inglês. **API de WhatsApp** — a camada específica do canal, com o que só o WhatsApp tem. Continua existindo e não muda; quem já integrou com ela não precisa migrar. Toda requisição se autentica por cabeçalho. Não há autenticação por corpo nem por query string. servers: - url: https://api.wizebot.com.br/v1 description: Produção security: - bearerAuth: [] tags: - name: Canais description: Contas de canal conectadas e o que cada uma aceita. - name: Mensagens description: Envio e status pelo contrato neutro, em qualquer canal. - name: WhatsApp · Mensagens description: Envio, status e modelos na camada específica de WhatsApp. - name: WhatsApp · Contatos description: Contatos e campos personalizados. - name: WhatsApp · Etiquetas description: Etiquetas e sua atribuição a contatos. - name: WhatsApp · Sequências description: Sequências agendadas de um contato. - name: WhatsApp · Conta description: Verificação da chave de API. paths: /whatsapp/contacts: get: tags: - WhatsApp · Contatos summary: Listar contatos description: >- Contatos vinculados a um número de WhatsApp, do mais recente para o mais antigo. operationId: whatsappListarContatos parameters: - name: phone_number_id in: query required: true schema: type: string description: Identificador do seu número de WhatsApp na Meta. example: '102938475610293' - name: limit in: query required: false schema: type: integer default: 20 maximum: 100 description: Quantos contatos trazer. Teto de 100. example: 20 - name: offset in: query required: false schema: type: integer default: 0 description: Quantos pular. example: 0 responses: '200': description: Lista de contatos. content: application/json: schema: type: object required: - success - data - timestamp properties: success: type: boolean description: Sempre `true` nas respostas de sucesso. data: type: object properties: items: type: array items: type: object properties: id: type: string phone_number: type: string name: type: - string - 'null' email: type: - string - 'null' gender: type: - string - 'null' tag_names: type: string description: >- Nomes das etiquetas do contato, separados por vírgula. Vazio quando não há. limit: type: integer offset: type: integer timestamp: type: string format: date-time example: success: true data: items: - id: 9c8b7a65-4321-4def-8abc-1234567890ab phone_number: '5511999999999' name: Maria Souza email: null gender: null tag_names: Cliente,VIP limit: 20 offset: 0 timestamp: '2026-09-09T17:15:20.453Z' '400': description: '`MISSING_PARAM` — phone_number_id is required.' content: application/json: schema: $ref: '#/components/schemas/ErroDaApi' examples: MISSING_PARAM: summary: MISSING_PARAM value: success: false statusCode: 400 timestamp: '2026-09-09T17:15:20.453Z' path: /api/v1/whatsapp/contacts method: GET message: error: MISSING_PARAM message: phone_number_id is required. errorId: ERR-MTUD0DBO-KKRMP8 '401': description: '`UNAUTHORIZED` — Invalid or missing API key.' content: application/json: schema: $ref: '#/components/schemas/ErroDaApi' examples: UNAUTHORIZED: summary: UNAUTHORIZED value: success: false statusCode: 401 timestamp: '2026-09-09T17:15:20.453Z' path: /api/v1/whatsapp/contacts method: GET message: error: UNAUTHORIZED message: Invalid or missing API key. errorId: ERR-MTUD0DBO-KKRMP8 '404': description: '`CHANNEL_NOT_FOUND` — Invalid phone_number_id or channel not found.' content: application/json: schema: $ref: '#/components/schemas/ErroDaApi' examples: CHANNEL_NOT_FOUND: summary: CHANNEL_NOT_FOUND value: success: false statusCode: 404 timestamp: '2026-09-09T17:15:20.453Z' path: /api/v1/whatsapp/contacts method: GET message: error: CHANNEL_NOT_FOUND message: Invalid phone_number_id or channel not found. errorId: ERR-MTUD0DBO-KKRMP8 '429': description: '`RATE_LIMITED` — Too many requests.' content: application/json: schema: $ref: '#/components/schemas/ErroDaApi' examples: RATE_LIMITED: summary: RATE_LIMITED value: success: false statusCode: 429 timestamp: '2026-09-09T17:15:20.453Z' path: /api/v1/whatsapp/contacts method: GET message: error: RATE_LIMITED message: Too many requests. errorId: ERR-MTUD0DBO-KKRMP8 components: schemas: ErroDaApi: type: object description: >- Corpo de erro da API. `message` é um **objeto** com o código nomeado — não uma string. required: - success - statusCode - message properties: success: type: boolean description: Sempre `false`. statusCode: type: integer timestamp: type: string format: date-time path: type: string description: >- Caminho interno da requisição. Traz o prefixo `/api/v1` mesmo quando você chamou por `/v1`: o apelido é reescrito antes do roteamento. method: type: string message: type: object required: - error - message properties: error: type: string description: >- Código nomeado. É por ele que se trata o erro em código, nunca pelo texto. message: type: string description: Descrição em inglês, para leitura humana. details: type: object additionalProperties: true description: >- Contexto estruturado, presente nos códigos que o emitem — `CHANNEL_MISMATCH`, `NO_OPEN_CONVERSATION`, `RECIPIENT_NOT_ON_CHANNEL` e `UNSUPPORTED_CAPABILITY`. errorId: type: string description: Identificador do erro. Cite-o ao falar com o suporte. securitySchemes: bearerAuth: type: http scheme: bearer description: >- Chave de API no cabeçalho `Authorization: Bearer SUA-CHAVE`. A API também aceita `x-api-key: SUA-CHAVE` e `Authorization: ApiKey SUA-CHAVE` — as três formas são equivalentes, inclusive para o limite de requisições. A chave dá acesso total à conta e é de servidor para servidor: não a use em navegador ou aplicativo móvel. ````