> ## Documentation Index > Fetch the complete documentation index at: https://docs.wegly.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Listar chats > Lista WhatsApp e Instagram em ordenação unificada. Reutilize next_cursor para paginação estável. Filtros positivos de agendamento, Copilot e resposta do cliente excluem conversas Instagram. Registros de WhatsApp incluem `ai_attendance`, com o resumo do atendimento por agente de IA. Permissão da chave: crm/chats.read. O acesso também respeita a empresa e as permissões do usuário criador da chave. ## OpenAPI ````yaml /openapi.json get /integrations/external/chats openapi: 3.0.3 info: title: >- Integração Externa - Leads, Oportunidades, Tarefas, Arquivos, Propostas, Chats, Satisfação e Campos Personalizados version: 1.0.0 description: > Documentação oficial da API externa da Wegly para campos personalizados, leads, oportunidades, tarefas, arquivos, propostas, chats e satisfação (`/integrations/external/custom-fields`, `/integrations/external/files`, `/integrations/external/leads`, `/integrations/external/deals`, `/integrations/external/tasks`, `/integrations/external/proposals`, `/integrations/external/chats` e `/integrations/external/satisfaction`). Todas as descrições estão em português e refletem as regras aplicadas pelo serviço. servers: - url: https://api.wegly.com.br description: Ambiente de produção Wegly security: - bearerAuth: [] tags: - name: Campos Personalizados description: >- Consulta dos campos personalizados disponíveis para uso nas integrações externas. - name: Arquivos description: >- Upload e consulta de arquivos vinculados diretamente a leads ou oportunidades. Arquivos de proposta usam as rotas de anexos em Propostas. - name: Leads description: >- Operações de listagem, criação, consulta e atualização de leads via integração externa. - name: Oportunidades description: Operações de criação de oportunidades (deals) via integração externa. - name: Tarefas description: >- Operações de listagem, criação, consulta, atualização e remoção de tarefas vinculadas a leads, oportunidades, entregas, pessoas, organizações ou clientes. - name: Satisfação description: >- Geração de links públicos para formulários de satisfação via integração externa. - name: Propostas description: >- Operações de listagem, criação, consulta, atualização e remoção de propostas via integração externa, incluindo seus anexos (arquivos e documentos da biblioteca). - name: Chats description: >- Operações principais de listagem, criação, consulta e resumo de não lidas de chats via integração externa. paths: /integrations/external/chats: get: tags: - Chats summary: Listar chats description: >- Lista WhatsApp e Instagram em ordenação unificada. Reutilize next_cursor para paginação estável. Filtros positivos de agendamento, Copilot e resposta do cliente excluem conversas Instagram. Registros de WhatsApp incluem `ai_attendance`, com o resumo do atendimento por agente de IA. Permissão da chave: crm/chats.read. O acesso também respeita a empresa e as permissões do usuário criador da chave. operationId: externalChatsList parameters: - name: search in: query required: false schema: type: string description: >- No WhatsApp, procura no nome do perfil do contato e no nome da pessoa vinculada; termos com formato de telefone também procuram no número do contato, com ou sem o nono dígito. - name: skip in: query required: false schema: type: number default: 0 description: >- Quantidade de registros a pular; valores negativos são normalizados para zero. - name: take in: query required: false schema: type: number default: 10 description: Quantidade por página. O serviço limita o resultado a 50 registros. - name: cursor in: query required: false schema: type: string description: Cursor opaco retornado em next_cursor; substitui o avanço por skip. - name: channel_type in: query required: false schema: type: string enum: - WHATSAPP - INSTAGRAM description: Sem filtro, combina os canais. - name: channel_account_id in: query required: false schema: type: string format: uuid description: >- ID da conta do canal; sem channel_type, direciona a consulta a Instagram. - name: phone_id in: query required: false schema: type: string format: uuid description: ID do número WhatsApp; direciona a consulta a WhatsApp. - name: status in: query required: false schema: $ref: '#/components/schemas/ChatStatusEnum' description: '' - name: archived in: query required: false schema: type: string enum: - include - only description: >- Padrão exclui arquivados; include inclui todos; only retorna apenas arquivados. - name: priority in: query required: false schema: $ref: '#/components/schemas/ChatPriorityValue' description: '' - name: responsible_user_id in: query required: false schema: type: string format: uuid description: >- Filtro de responsável do WhatsApp; atualmente exclui Instagram. Um usuário que não é atendente do WhatsApp retorna lista vazia. - name: person_id in: query required: false schema: type: string format: uuid description: '' - name: unread_only in: query required: false schema: type: boolean description: true considera unread_count > 0 ou is_manually_unread=true. - name: has_scheduled_messages in: query required: false schema: type: boolean description: >- true filtra WhatsApp com mensagem agendada PENDING/PROCESSING, independentemente da data. - name: has_pending_copilot_actions in: query required: false schema: type: boolean description: true filtra WhatsApp com ações pendentes de revisão. - name: customer_reply_status in: query required: false schema: type: string enum: - initial_replied - initial_not_replied - not_replied_last_messages description: Filtro de resposta do cliente em conversas WhatsApp. - name: customer_reply_message_count in: query required: false schema: type: integer minimum: 1 maximum: 50 description: >- Quantidade de mensagens sem resposta (padrão efetivo 1), usada por not_replied_last_messages. responses: '200': description: Operação realizada. content: application/json: schema: $ref: '#/components/schemas/ChatListResponse' '400': description: Payload ou regra de negócio inválidos. '401': description: >- Chave de integração ausente, inválida, inativa ou expirada, ou domínio de origem não autorizado para a chave. '403': description: Permissão da chave ou do usuário insuficiente para o recurso. '404': description: Conversa ou recurso associado não encontrado no escopo acessível. '429': description: Limite de requisições da integração excedido. '500': description: Falha interna ou na comunicação com o provedor. components: schemas: ChatStatusEnum: type: string enum: - OPEN - RESOLVED - SNOOZED ChatPriorityValue: type: integer enum: - 0 - 1 - 2 - 3 description: 0 = baixa, 1 = normal, 2 = alta, 3 = urgente. ChatListResponse: type: object properties: total: type: integer description: Total de registros que correspondem à consulta. records: type: array items: anyOf: - $ref: '#/components/schemas/ChatSummary' - $ref: '#/components/schemas/ChatInstagramSummary' next_cursor: type: string nullable: true description: Cursor opaco da próxima página; null quando não há continuação. required: - total - records - next_cursor ChatSummary: type: object properties: id: type: string format: uuid wa_contact_id: type: string contact_name: type: string contact_number: type: string status: $ref: '#/components/schemas/ChatStatusEnum' chat_type: $ref: '#/components/schemas/ChatTypeEnum' unread_count: type: integer is_manually_unread: type: boolean priority: $ref: '#/components/schemas/ChatPriorityValue' archived_at: type: string format: date-time nullable: true assigned_agent_id: type: string format: uuid nullable: true phone_number: $ref: '#/components/schemas/ChatPhoneSummary' assigned_agent: type: object allOf: - $ref: '#/components/schemas/ChatAgentSummary' nullable: true last_message_at: type: string format: date-time nullable: true last_message: type: object allOf: - $ref: '#/components/schemas/ChatMessageSummary' nullable: true crm_person: type: object allOf: - $ref: '#/components/schemas/ChatCrmPersonSummary' nullable: true last_customer_msg_at: type: string format: date-time nullable: true session_expires_at: type: string format: date-time nullable: true can_send_open_message: type: boolean description: Indica se a janela atual permite mensagem aberta. has_pending_copilot_actions: type: boolean pending_copilot_actions_count: type: integer has_active_whatsapp_flow_session: type: boolean active_whatsapp_flow_sessions: type: array items: $ref: '#/components/schemas/ChatActiveFlowSession' has_upcoming_scheduled_message: type: boolean description: Presente na listagem; indica agendamento futuro. channel_type: type: string enum: - WHATSAPP channel_account_id: type: string format: uuid channel_account: $ref: '#/components/schemas/ChatChannelAccount' external_contact: $ref: '#/components/schemas/ChatExternalContact' legacy: type: object properties: whatsapp_chat_id: type: string format: uuid whatsapp_phone_id: type: string format: uuid wa_contact_id: type: string ai_attendance: type: object allOf: - $ref: '#/components/schemas/ChatAiAttendance' nullable: true description: >- Presente nos registros de WhatsApp da listagem; null quando a conversa nunca teve agente de IA ou o recurso está desativado. Não faz parte da criação nem dos detalhes. required: - id - wa_contact_id - contact_name - contact_number - status - priority - chat_type - unread_count - is_manually_unread - channel_type - channel_account_id - can_send_open_message ChatInstagramSummary: type: object properties: id: type: string format: uuid wa_contact_id: type: string nullable: true description: Sempre null nas conversas Instagram. contact_name: type: string contact_number: type: string status: $ref: '#/components/schemas/ChatStatusEnum' chat_type: $ref: '#/components/schemas/ChatTypeEnum' unread_count: type: integer is_manually_unread: type: boolean priority: $ref: '#/components/schemas/ChatPriorityValue' archived_at: type: string format: date-time nullable: true assigned_agent_id: type: string format: uuid nullable: true phone_number: $ref: '#/components/schemas/ChatPhoneSummary' assigned_agent: type: object allOf: - $ref: '#/components/schemas/ChatAgentSummary' nullable: true last_message_at: type: string format: date-time nullable: true last_message: type: object allOf: - $ref: '#/components/schemas/ChatInstagramMessage' nullable: true crm_person: type: object allOf: - $ref: '#/components/schemas/ChatPersonDetails' nullable: true last_customer_msg_at: type: string format: date-time nullable: true session_expires_at: type: string format: date-time nullable: true can_send_open_message: type: boolean description: Indica se a janela atual permite mensagem aberta. has_pending_copilot_actions: type: boolean pending_copilot_actions_count: type: integer has_active_whatsapp_flow_session: type: boolean active_whatsapp_flow_sessions: type: array items: $ref: '#/components/schemas/ChatActiveFlowSession' has_upcoming_scheduled_message: type: boolean description: Presente na listagem; indica agendamento futuro. channel_type: type: string enum: - INSTAGRAM channel_account_id: type: string format: uuid channel_account: $ref: '#/components/schemas/ChatChannelAccount' external_contact: $ref: '#/components/schemas/ChatExternalContact' legacy: type: object properties: {} description: Objeto vazio para Instagram. created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - wa_contact_id - contact_name - contact_number - status - priority - chat_type - unread_count - is_manually_unread - channel_type - channel_account_id - can_send_open_message ChatTypeEnum: type: string enum: - INDIVIDUAL - GROUP ChatPhoneSummary: type: object properties: id: type: string format: uuid display_number: type: string nullable: true ChatAgentSummary: type: object properties: agent_id: type: string format: uuid user: type: object allOf: - $ref: '#/components/schemas/ExternalUserSummary' nullable: true ChatMessageSummary: type: object properties: id: type: string format: uuid type: $ref: '#/components/schemas/ChatMessageTypeEnum' origin: $ref: '#/components/schemas/ChatMessageOriginEnum' from_me: type: boolean sent_via: $ref: '#/components/schemas/ChatMessageSentViaEnum' status: $ref: '#/components/schemas/ChatMessageDeliveryStatusEnum' body_text: type: string nullable: true content_payload: type: object nullable: true additionalProperties: true reactions: type: array items: $ref: '#/components/schemas/ChatReaction' meta_timestamp: type: string format: date-time is_history: type: boolean history_phase: type: integer nullable: true history_chunk_order: type: integer nullable: true history_progress: type: integer nullable: true is_media_placeholder: type: boolean agent: type: object nullable: true properties: id: type: string format: uuid user: type: object allOf: - $ref: '#/components/schemas/ExternalUserSummary' nullable: true user: type: object allOf: - $ref: '#/components/schemas/ExternalUserSummary' nullable: true crm_marketing_lead_source: type: array nullable: true items: type: object additionalProperties: true transcription: type: string nullable: true is_forwarded: type: boolean whatsapp_ai_agent_id: type: string format: uuid nullable: true description: >- Agente de IA que enviou a mensagem; null para pessoas e automações. Em `last_message`, é preenchido apenas na listagem de chats. ChatCrmPersonSummary: type: object properties: id: type: string format: uuid name: type: string ChatActiveFlowSession: allOf: - $ref: '#/components/schemas/ChatFlowSession' - type: object properties: journey: type: object properties: completed_steps: type: array items: $ref: '#/components/schemas/ChatFlowStep' current_step: type: object allOf: - $ref: '#/components/schemas/ChatFlowStep' nullable: true upcoming_steps: type: array items: $ref: '#/components/schemas/ChatFlowStep' ChatChannelAccount: type: object properties: id: type: string format: uuid type: type: string description: WHATSAPP_PHONE para WhatsApp; tipo da conta para Instagram. display_name: type: string nullable: true provider_status: type: string ChatExternalContact: type: object properties: id: type: string handle: type: string nullable: true display_name: type: string nullable: true avatar_url: type: string nullable: true ChatAiAttendance: type: object description: >- Resumo do atendimento por agente de IA em uma conversa WhatsApp da listagem. properties: state: type: string enum: - AI - TRANSFERRED - TEAM description: >- AI: o agente conduz a conversa. TRANSFERRED: transferida pelo agente e ainda sem resposta de uma pessoa. TEAM: com a equipe. agent: type: object properties: id: type: string format: uuid name: type: string profile_name: type: string nullable: true since: type: string format: date-time nullable: true description: >- Com o agente atendendo, início do atendimento; depois, momento em que o agente saiu da conversa. end_reason: type: string nullable: true enum: - TRANSFER_RULE - FALLBACK - RESPONSE_LIMIT - HUMAN_REPLY - MANUAL_ASSIGNMENT - CHAT_RESOLVED - AI_COINS_EXHAUSTED - OUTSIDE_ACTIVE_HOURS description: >- Motivo do encerramento do atendimento pelo agente; null enquanto ele conduz a conversa. transferred_to: type: object nullable: true description: Pessoa que recebeu a conversa na transferência. properties: id: type: string format: uuid name: type: string ChatInstagramMessage: type: object properties: id: type: string format: uuid type: type: string description: Tipo normalizado da mensagem do canal. origin: type: string enum: - INBOUND - API_OUTBOUND - APP_ECHO - SYSTEM from_me: type: boolean sent_via: $ref: '#/components/schemas/ChatMessageSentViaEnum' status: type: string enum: - PROCESSING - SENT - DELIVERED - READ - FAILED - DELETED description: Status da mensagem no Instagram, em maiúsculas. body_text: type: string nullable: true content_payload: type: object nullable: true additionalProperties: true reactions: type: array items: $ref: '#/components/schemas/ChatReaction' meta_timestamp: type: string format: date-time is_history: type: boolean history_phase: type: integer nullable: true history_chunk_order: type: integer nullable: true history_progress: type: integer nullable: true is_media_placeholder: type: boolean agent: type: object nullable: true properties: id: type: string format: uuid user: type: object allOf: - $ref: '#/components/schemas/ExternalUserSummary' nullable: true user: type: object allOf: - $ref: '#/components/schemas/ExternalUserSummary' nullable: true crm_marketing_lead_source: type: array nullable: true items: type: object additionalProperties: true is_forwarded: type: boolean wamid: type: string nullable: true provider_message_id: type: string nullable: true ref_wamid: type: string nullable: true ref_provider_message_id: type: string nullable: true error_code: type: string nullable: true description: Código textual do erro, por exemplo `DELIVERY_UNKNOWN`. error_message: type: string nullable: true shared_content: type: object properties: {} nullable: true additionalProperties: true media: type: array items: $ref: '#/components/schemas/ChatInstagramAttachment' attachments: type: array items: $ref: '#/components/schemas/ChatInstagramAttachment' provider_timestamp: type: string format: date-time channel_type: type: string enum: - INSTAGRAM quoted_message: allOf: - $ref: '#/components/schemas/ChatInstagramMessage' - type: object properties: page: type: integer required: - id - type - origin - from_me - sent_via - status - body_text - meta_timestamp - media - attachments - channel_type ChatPersonDetails: type: object properties: id: type: string format: uuid name: type: string birth_date: type: string format: date-time nullable: true gender: type: integer nullable: true notes: type: string nullable: true contacts: type: array items: $ref: '#/components/schemas/ChatPersonContact' documents: type: array items: $ref: '#/components/schemas/ChatPersonDocument' address: type: object allOf: - $ref: '#/components/schemas/ChatPersonAddress' nullable: true ExternalUserSummary: type: object properties: id: type: string format: uuid name: type: string avatar: type: string nullable: true ChatMessageTypeEnum: type: string enum: - text - reaction - image - video - audio - document - template - interactive - location - call - contacts - unsupported - sticker - button description: >- Tipos mais comuns. Mensagens recebidas guardam o tipo informado pelo provedor, de modo que outros valores podem aparecer. ChatMessageOriginEnum: type: string enum: - INBOUND - API_OUTBOUND - MOBILE_APP_ECHO - SYSTEM ChatMessageSentViaEnum: type: string enum: - CONTACT - API - MOBILE_DEVICE - SYSTEM ChatMessageDeliveryStatusEnum: type: string enum: - processing - sent - delivered - read - failed - received - deleted - delivery_unknown description: >- Status persistido da mensagem; delivery_unknown indica que o resultado do envio ainda não foi confirmado. ChatReaction: type: object properties: id: type: string format: uuid emoji: type: string actor: type: string enum: - CONTACT - BUSINESS - SYSTEM description: '`SYSTEM` pode aparecer em reações do Instagram.' reactor_wa_id: type: string reactor_user_id: type: string format: uuid nullable: true created_at: type: string format: date-time ChatFlowSession: type: object properties: session_id: type: string format: uuid flow_id: type: string format: uuid flow_name: type: string status: type: string enum: - ACTIVE - WAITING_INPUT - WAITING_TIME - PAUSED_BY_HUMAN - TRANSFERRED - COMPLETED - FAILED - CANCELED status_label: type: string is_active: type: boolean started_at: type: string format: date-time last_activity_at: type: string format: date-time finished_at: type: string format: date-time nullable: true current_step: type: object allOf: - $ref: '#/components/schemas/ChatFlowStep' nullable: true ChatFlowStep: type: object properties: node_id: type: string node_key: type: string name: type: string status: type: string nullable: true status_label: type: string nullable: true branch_key: type: string nullable: true branch_label: type: string nullable: true started_at: type: string format: date-time nullable: true finished_at: type: string format: date-time nullable: true ChatInstagramAttachment: type: object properties: id: type: string format: uuid media_id: type: string nullable: true provider_media_id: type: string nullable: true provider_type: type: string nullable: true content_kind: type: string mime_type: type: string nullable: true file_name: type: string nullable: true file_size: type: number nullable: true storage_path: type: string nullable: true public_url: type: string nullable: true source_url: type: string nullable: true url: type: string nullable: true is_downloaded: type: boolean download_status: type: string metadata: type: object properties: {} nullable: true additionalProperties: true ChatPersonContact: type: object properties: id: type: string format: uuid type: type: integer value: type: string primary: type: boolean ChatPersonDocument: type: object properties: id: type: string format: uuid type: type: integer label: type: string nullable: true value: type: string ChatPersonAddress: type: object properties: id: type: string format: uuid status: type: integer type: type: integer name: type: string nullable: true street: type: string nullable: true number: type: string nullable: true complement: type: string nullable: true district: type: string nullable: true city: type: string nullable: true state: type: string nullable: true postal_code: type: string nullable: true securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: >- Chave de integração com prefixo wegly_, enviada em Authorization: Bearer . Não é JWT. A chave deve estar ativa, não excluída e dentro da validade. Com allowed_domain, Origin (ou Referer na ausência de Origin) precisa informar o hostname permitido. A empresa e as permissões são obtidas pela chave. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.