> ## Documentation Index > Fetch the complete documentation index at: https://docs.liderhub.ai/llms.txt > Use this file to discover all available pages before exploring further. # Consultar conversas / contatos > Lista conversas individuais do workspace. ## OpenAPI ````yaml /openapi/liderhub.json get /v1/contacts openapi: 3.0.0 info: title: API Liderhub description: >- API REST para gerenciamento de conversas WhatsApp com IA. ## Autenticação A autenticação é obrigatória e deve ser feita utilizando o header `x-company-key`, gerado diretamente na plataforma Liderhub. Cada workspace possui uma chave própria, garantindo isolamento e segurança. ## Recursos disponíveis | Recurso | Descrição | |---------|-----------| | **Connections** | Gerenciar conexões WhatsApp do workspace | | **Contacts** | Listar, buscar, cadastrar contatos e marcar como lidos | | **Message** | Listar, buscar, enviar e cancelar mensagens agendadas | | **Agents** | Listar agentes de IA configurados | | **Users** | Listar usuários do workspace | | **Settings** | Consultar e atribuir status, origens, tags e departamentos aos chats | | **Groups** | Grupos WhatsApp: listar, detalhar, criar, atualizar nome/foto/configurações e gerenciar participantes e admins | | **Templates** | Listar, obter e enviar mensagens rápidas (templates) | ## Paginação Endpoints que retornam listas suportam paginação: - `page`: número da página (inicia em 1) - `limit`: itens por página (máximo 100) Retorno inclui metadados em `pagination`: page, limit, total, totalPages, hasNextPage, hasPreviousPage ## Filtros de lista (GET /v1/contacts) | Filtro | Tipo | Descrição | |--------|------|-----------| | `number` | string | Filtrar por número de telefone | | `connection` | UUID | Filtrar por conexão | | `id` | UUID | Filtrar por chat/contato — no máximo um resultado | | `department` | UUID | Filtrar por departamento | | `tags` | UUID | Filtrar por tag(s) - separar por vírgula | | `status` | UUID | Filtrar por status | | `stage` | enum | Filtrar por estágio: Open, Closed, Pending | | `hasUnread` | boolean | Filtrar contacts com mensagens não lidas | | `createdAfter` | ISO8601 | Criados após data | | `createdBefore` | ISO8601 | Criados antes de data | | `modifiedAfter` | ISO8601 | Modificados após data | | `modifiedBefore` | ISO8601 | Modificados antes de data | ⚠️ **Importante**: Utilize esta API de maneira responsável. Não forneça a credencial para terceiros. version: 1.0.0 contact: {} servers: - url: https://api.liderhub.com.br description: Produção security: [] tags: - name: Connections description: Gerenciar conexões WhatsApp do workspace - name: Contacts description: 'Contatos/conversas: listar e filtrar contatos.' - name: Message description: Listar, buscar, enviar e cancelar mensagens agendadas - name: Agents description: Listar agentes de IA configurados - name: Users description: Listar usuários do workspace - name: Settings description: Consultar e atribuir status, origens, tags e departamentos aos chats - name: Groups description: Gestão de grupos WhatsApp - name: Templates description: Templates / mensagens rápidas paths: /v1/contacts: get: tags: - Contacts summary: Consultar conversas / contatos description: Lista conversas individuais do workspace. operationId: ContactController_listConversations parameters: - name: number required: false in: query description: Filtrar por número de telefone schema: example: '5511999999999' type: string - name: connection required: false in: query description: Filtrar por ID da conexão schema: example: aaaaaaaa-bbbb-cccc-dddd-111111111111 type: string - name: id required: false in: query description: UUID do chat/contato — filtra no máximo um registro schema: format: uuid example: 1cbcb7a8-8bf6-4016-8ed5-8ea38c4a9a05 type: string - name: createdAfter required: false in: query description: Filtrar contacts criados após esta data (ISO 8601) schema: example: '2026-01-01T00:00:00Z' type: string - name: createdBefore required: false in: query description: Filtrar contacts criados antes desta data (ISO 8601) schema: example: '2026-12-31T23:59:59Z' type: string - name: modifiedAfter required: false in: query description: Filtrar contacts modificados após esta data (ISO 8601) schema: example: '2026-01-01T00:00:00Z' type: string - name: modifiedBefore required: false in: query description: Filtrar contacts modificados antes desta data (ISO 8601) schema: example: '2026-12-31T23:59:59Z' type: string - name: status required: false in: query description: Filtrar por ID do status (UUID) schema: example: aaaaaaaa-bbbb-cccc-dddd-111111111111 type: string - name: stage required: false in: query description: Filtrar por estágio do ticket schema: enum: - Open - Closed - Pending type: string - name: hasUnread required: false in: query description: Filtrar contacts com mensagens não lidas (true/false) schema: type: boolean example: true - name: department required: false in: query description: Filtrar por ID do departamento (UUID) schema: example: aaaaaaaa-bbbb-cccc-dddd-111111111111 type: string - name: tags required: false in: query description: Filtrar por tag(s) — UUIDs separados por vírgula schema: example: aaaaaaaa-bbbb-cccc-dddd-111111111111 type: string - name: page required: false in: query description: 'Página (começa em 1, padrão: 1)' schema: default: 1 example: 1 type: number - name: limit required: false in: query description: 'Itens por página (padrão: 20, máximo: 100)' schema: default: 20 example: 20 type: number responses: '200': description: Lista de conversas retornada com sucesso content: application/json: schema: $ref: '#/components/schemas/ChatsListResponseDto' '400': description: Requisição inválida — filtros mal formatados '401': description: Não autorizado — chave de empresa inválida ou ausente security: - x-company-key: [] components: schemas: ChatsListResponseDto: type: object properties: contacts: type: array items: $ref: '#/components/schemas/ChatResponseDto' pagination: description: Pagination metadata for chat listing allOf: - $ref: '#/components/schemas/ChatsPaginationDto' required: - contacts - pagination ChatResponseDto: type: object properties: id: type: string description: UUID do chat/contato format: uuid example: aaaaaaaa-bbbb-cccc-dddd-111111111111 contactNumber: type: string description: Contact phone number example: '5511999999999' contactName: type: string description: Contact name nullable: true example: João Silva department: type: string description: Department ID nullable: true format: uuid example: bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb status: type: string description: Status label ID nullable: true format: uuid example: cccccccc-cccc-cccc-cccc-cccccccccccc source: type: string description: Source label ID nullable: true format: uuid example: dddddddd-dddd-dddd-dddd-dddddddddddd connection: type: string description: Connection ID nullable: true format: uuid example: eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee agent: type: string description: AI agent ID nullable: true format: uuid example: ffffffff-ffff-ffff-ffff-ffffffffffff user: type: string description: Human agent (company user) ID nullable: true format: uuid example: 11111111-2222-3333-4444-555555555555 ticketStatus: type: string description: Ticket status enum: - open - closed - pending nullable: true example: open createdAt: type: string description: Chat creation date (ISO string) nullable: true format: date-time example: '2026-04-16T15:30:00.000Z' integration: type: string description: Normalized integration type enum: - WHATSAPP-NON-OFFICIAL - WHATSAPP-BUSINESS example: WHATSAPP-NON-OFFICIAL lastInteraction: type: string description: >- Last interaction date (ISO string). Returned only for official integrations. nullable: true format: date-time example: '2026-04-16T14:00:00.000Z' isWhatsAppWindowClosed: type: boolean description: >- True when WhatsApp conversation window is closed. Returned only for official integrations. nullable: true example: false tags: description: Tags array nullable: true example: - aaaaaaaa-bbbb-cccc-dddd-111111111111 type: array items: type: string required: - id - contactNumber - integration ChatsPaginationDto: type: object properties: page: type: number example: 1 limit: type: number example: 20 total: type: number example: 154 totalPages: type: number example: 8 hasNextPage: type: boolean example: true hasPreviousPage: type: boolean example: false required: - page - limit - total - totalPages - hasNextPage - hasPreviousPage securitySchemes: x-company-key: type: apiKey in: header name: x-company-key description: Chave de autenticação do workspace (gerada na plataforma Liderhub) ````