> ## 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. # Cadastrar contato > Cria um contato após validar o número no WhatsApp. **Obrigatórios:** `connection` (UUID — `id` de GET /v1/connections), `number` (DDI + DDD + telefone ). **Opcionais:** `name`, `email`, `agent`, `user`, `status`. ## OpenAPI ````yaml /openapi/liderhub.json post /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: post: tags: - Contacts summary: Cadastrar contato description: >- Cria um contato após validar o número no WhatsApp. **Obrigatórios:** `connection` (UUID — `id` de GET /v1/connections), `number` (DDI + DDD + telefone ). **Opcionais:** `name`, `email`, `agent`, `user`, `status`. operationId: ContactCreateController_create parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateContactDto' examples: comOpcionais: summary: >- Obrigatórios + opcionais: name, email, agent (Agente de IA), user (Usuário humano), status (Status do workspace). OBS: `agent` e `user` são UUIDs validados no workspace é somente é possivel definir um deles. value: connection: e3c9be60-fbe0-4630-abd2-d6b3d699c9b2 number: '554892171075' name: Maria Silva email: maria@empresa.com.br agent: 3fa85f64-5717-4562-b3fc-2c963f66afa6 user: 11111111-2222-3333-4444-555555555555 status: 3fa85f64-5717-4562-b3fc-2c963f66afa6 apenasObrigatorios: summary: Somente connection e number value: connection: be65dc43-a3b8-46d7-8185-66df68010041 number: '554892171075' responses: '200': description: >- `exist: false` se o número não for WhatsApp válido; caso contrário `exist`, `id` e `created`. content: application/json: schema: $ref: '#/components/schemas/CreateContactResponseDto' '400': description: >- Corpo inválido — validação de campos (ex.: `agent` / `user` / `status` inexistentes no workspace) '401': description: Não autorizado — chave de empresa inválida ou ausente '404': description: Conexão não encontrada para este workspace '500': description: Erro ao criar ou atualizar o chat '503': description: Erro ao validar o número WhatsApp security: - x-company-key: [] components: schemas: CreateContactDto: type: object properties: connection: type: string format: uuid description: ID da conexão — o mesmo `id` retornado em GET /v1/connections. example: e3c9be60-fbe0-4630-abd2-d6b3d699c9b2 number: type: string description: Número para validação no WhatsApp (DDI + dígitos, com ou sem +). example: '554892171075' name: type: string description: Nome exibido no chat (string; não envie objeto). example: Maria Silva email: type: string description: E-mail associado ao contato (string). example: maria@empresa.com.br agent: type: string format: uuid description: Agente de IA — mesmo `id` que recebe em GET /v1/agents. user: type: string format: uuid description: Usuário humano — mesmo campo `user` que recebe em GET /v1/users. status: type: string format: uuid description: >- Label de status — mesmo campo `status` na resposta de chat. GET /v1/settings/status. required: - connection - number CreateContactResponseDto: type: object properties: exist: type: boolean description: Indica se o número existe no WhatsApp. example: true id: type: string format: uuid description: 'Presente quando `exist` é true: UUID do chat/contato.' example: 1cbcb7a8-8bf6-4016-8ed5-8ea38c4a9a05 created: type: boolean description: >- Presente quando `exist` é true: true se o chat foi criado nesta chamada. example: true required: - exist securitySchemes: x-company-key: type: apiKey in: header name: x-company-key description: Chave de autenticação do workspace (gerada na plataforma Liderhub) ````