# Consultar detalhes de um chat

POST /chat/details

Retorna os dados disponíveis para apresentar ou editar uma conversa:
identificação, nomes conhecidos, telefone, foto, estado do chat, dados de
lead e informações de grupo quando aplicáveis.

Use depois de escolher um chat em `POST /chat/find`. Para obter somente a
imagem, prefira `POST /chat/avatar`, mais leve, principalmente em listas com
muitos chats. O campo `preview` permite escolher uma imagem menor para
interfaces de listagem ou a imagem completa.

Cada instância processa até 4 consultas desta rota ao mesmo tempo. A
seguinte espera até 2 segundos por uma vaga; se não houver, recebe `429`
com o header `Retry-After`. A rota também conta no limite de chamadas da
instância.

Para contatos individuais, `is_business` indica se há um nome comercial
conhecido. `business_name` traz esse nome quando disponível.


## Autenticação

```json
[
  {
    "token": []
  }
]
```

```json
{
  "token": {
    "name": "token",
    "type": "apiKey",
    "in": "header"
  }
}
```

## Corpo da requisição

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "number": {
            "type": "string",
            "description": "Número do telefone ou ID do grupo",
            "example": "5511999999999"
          },
          "preview": {
            "type": "boolean",
            "description": "Controla o tamanho da imagem de perfil retornada:\n- `true`: Retorna imagem em tamanho preview (menor, otimizada para listagens)\n- `false` (padrão): Retorna imagem em tamanho full (resolução original, maior qualidade)\n",
            "default": false
          }
        },
        "required": [
          "number"
        ]
      }
    }
  }
}
```

## Respostas

```json
{
  "200": {
    "description": "Informações completas do chat retornadas com sucesso",
    "content": {
      "application/json": {
        "schema": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Chat"
            },
            {
              "type": "object",
              "properties": {
                "is_business": {
                  "type": "boolean",
                  "description": "Há um nome comercial conhecido para este contato."
                },
                "business_name": {
                  "type": "string",
                  "description": "Nome comercial conhecido, ou string vazia."
                },
                "wa_common_groups": {
                  "type": "string",
                  "description": "Grupos em comum separados por vírgula, formato: nome_grupo(id_grupo)",
                  "example": "Grupo Família(120363123456789012@g.us),Trabalho(987654321098765432@g.us)"
                },
                "imagePreview": {
                  "type": "string",
                  "description": "URL da foto de perfil em tamanho menor; vazia se não houver."
                },
                "image": {
                  "type": "string",
                  "description": "URL da foto de perfil em tamanho original; vazia se não houver."
                }
              }
            }
          ]
        },
        "examples": {
          "contact_example": {
            "summary": "Contato individual",
            "description": "Exemplo de resposta para um contato individual",
            "value": {
              "id": "r1a2b3c4d5e6f7",
              "wa_fastid": "admin:5511999999999",
              "wa_chatid": "5511999999999@s.whatsapp.net",
              "wa_name": "João Silva",
              "name": "João Silva",
              "phone": "+55 11 99999-9999",
              "owner": "admin",
              "wa_archived": false,
              "wa_isBlocked": false,
              "wa_isGroup": false,
              "lead_name": "João",
              "lead_fullName": "João Silva",
              "lead_email": "joao@exemplo.com",
              "lead_status": "ativo",
              "wa_contactName": "João Silva",
              "is_business": false,
              "business_name": "",
              "wa_common_groups": "Grupo Família(120363123456789012@g.us),Trabalho(987654321098765432@g.us)",
              "image": "https://pps.whatsapp.net/v/t61.24694-24/12345_image.jpg"
            }
          },
          "group_example": {
            "summary": "Grupo",
            "description": "Exemplo de resposta para um grupo",
            "value": {
              "id": "r9z8y7x6w5v4u3",
              "wa_fastid": "admin:120363123456789012@g.us",
              "wa_chatid": "120363123456789012@g.us",
              "wa_name": "Grupo Família",
              "name": "Grupo Família",
              "phone": "",
              "owner": "admin",
              "wa_archived": false,
              "wa_isBlocked": false,
              "wa_isGroup": true,
              "wa_isGroup_admin": true,
              "wa_isGroup_announce": false,
              "wa_isGroup_community": false,
              "wa_isGroup_member": true,
              "image": "https://pps.whatsapp.net/v/t61.24694-24/67890_group.jpg"
            }
          }
        }
      }
    }
  },
  "400": {
    "description": "Payload inválido ou número inválido",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "error": {
              "type": "string",
              "example": "Invalid request payload"
            }
          }
        }
      }
    }
  },
  "401": {
    "description": "Token não fornecido",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "error": {
              "type": "string",
              "example": "Unauthorized"
            }
          }
        }
      }
    }
  },
  "429": {
    "description": "Limite de chamadas da instância ou de consultas simultâneas desta rota",
    "headers": {
      "Retry-After": {
        "description": "Segundos até a próxima chamada ser aceita.",
        "schema": {
          "type": "integer"
        }
      }
    },
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "error": {
              "type": "string",
              "example": "rate limit exceeded"
            }
          }
        }
      }
    }
  },
  "500": {
    "description": "Erro interno do servidor ou sessão não iniciada",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "error": {
              "type": "string",
              "example": "No session"
            }
          }
        }
      }
    }
  }
}
```

## #/components/schemas/Chat

```json
{
  "type": "object",
  "description": "Representa uma conversa/chamado no sistema",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID único da conversa (r + 7 bytes aleatórios em hex)"
    },
    "wa_fastid": {
      "type": "string",
      "description": "Identificador rápido do WhatsApp"
    },
    "wa_chatid": {
      "type": "string",
      "description": "ID completo do chat no WhatsApp"
    },
    "wa_chatlid": {
      "type": "string",
      "description": "LID do chat no WhatsApp (quando disponível)"
    },
    "wa_archived": {
      "type": "boolean",
      "description": "Indica se o chat está arquivado",
      "default": false
    },
    "wa_contactName": {
      "type": "string",
      "description": "Nome salvo na agenda do celular deste número (vazio: não está salvo). A conversa nasce com ele (por LID, pelo número ligado) e ele muda quando o contato é salvo ou apagado no celular.\n",
      "default": ""
    },
    "wa_name": {
      "type": "string",
      "description": "Nome definido pelo usuário no perfil do WhatsApp (\"push name\").\nVem do perfil do contato e pode não estar disponível dependendo do contexto ou da origem dos dados.\n",
      "default": ""
    },
    "name": {
      "type": "string",
      "description": "Nome resolvido pelo sistema como fallback.\nNormalmente consolida o melhor valor disponível entre dados internos, nome vindo do WhatsApp e nome salvo nos contatos.\nPor isso, costuma ter maior chance de vir preenchido.\n",
      "default": ""
    },
    "image": {
      "type": "string",
      "description": "URL da imagem do chat",
      "default": ""
    },
    "imagePreview": {
      "type": "string",
      "description": "URL da miniatura da imagem",
      "default": ""
    },
    "parent_community": {
      "type": "object",
      "description": "Comunidade pai do chat quando ele representa um subgrupo",
      "properties": {
        "jid": {
          "type": "string",
          "format": "jid"
        },
        "name": {
          "type": "string"
        },
        "image_url": {
          "type": "string"
        },
        "image_preview_url": {
          "type": "string"
        },
        "default_subgroup_jid": {
          "type": "string",
          "format": "jid"
        }
      }
    },
    "wa_ephemeralExpiration": {
      "type": "integer",
      "format": "int64",
      "description": "Tempo de expiração de mensagens efêmeras",
      "default": 0
    },
    "wa_isBlocked": {
      "type": "boolean",
      "description": "Indica se o contato está bloqueado",
      "default": false
    },
    "wa_isGroup": {
      "type": "boolean",
      "description": "Indica se é um grupo",
      "default": false
    },
    "wa_isGroup_admin": {
      "type": "boolean",
      "description": "Indica se o usuário é admin do grupo",
      "default": false
    },
    "wa_isGroup_announce": {
      "type": "boolean",
      "description": "Indica se é um grupo somente anúncios",
      "default": false
    },
    "wa_isGroup_community": {
      "type": "boolean",
      "description": "Indica se é uma comunidade",
      "default": false
    },
    "wa_isGroup_member": {
      "type": "boolean",
      "description": "Indica se é membro do grupo",
      "default": false
    },
    "wa_isPinned": {
      "type": "boolean",
      "description": "Indica se o chat está fixado",
      "default": false
    },
    "wa_label": {
      "type": "array",
      "description": "Labels do chat",
      "items": {
        "type": "string"
      }
    },
    "wa_notes": {
      "type": "string",
      "description": "Anotações internas do chat sincronizadas via app state",
      "default": ""
    },
    "wa_lastMessageTextVote": {
      "type": "string",
      "description": "Texto/voto da última mensagem",
      "default": ""
    },
    "wa_lastMessageType": {
      "type": "string",
      "description": "Tipo da última mensagem",
      "default": ""
    },
    "wa_lastMsgTimestamp": {
      "type": "integer",
      "format": "int64",
      "description": "Timestamp da última mensagem",
      "default": 0
    },
    "wa_lastMessageSender": {
      "type": "string",
      "description": "Remetente da última mensagem",
      "default": ""
    },
    "lead_awaitingReply": {
      "type": "boolean",
      "readOnly": true,
      "description": "`true` quando o contato espera resposta: a última mensagem é dele e ninguém concluiu a conversa (`POST /lead/resolve`). A mensagem do contato liga; a nossa (você, a IA, um fluxo ou uma integração) desliga. Nas conversas anteriores a este campo, a api decide pelo remetente (o número ou o LID da instância). Só em conversas com pessoas: ausente em grupos e canais, que não entram em nenhum dos dois filtros, e quando a conversa não tem última mensagem conhecida (só a data). Filtrável no `/chat/find`."
    },
    "wa_muteEndTime": {
      "type": "integer",
      "format": "int64",
      "description": "Timestamp do fim do silenciamento",
      "default": 0
    },
    "owner": {
      "type": "string",
      "description": "Dono da instância",
      "default": ""
    },
    "wa_unreadCount": {
      "type": "integer",
      "format": "int64",
      "description": "Contador de mensagens não lidas",
      "default": 0
    },
    "phone": {
      "type": "string",
      "description": "Número de telefone",
      "default": ""
    },
    "common_groups": {
      "type": "string",
      "description": "Grupos em comum separados por vírgula, formato: (nome_grupo)id_grupo",
      "default": "",
      "example": "Grupo Família(120363123456789012@g.us),Trabalho(987654321098765432@g.us)"
    },
    "lead_name": {
      "type": "string",
      "description": "Nome do lead",
      "default": ""
    },
    "lead_fullName": {
      "type": "string",
      "description": "Nome completo do lead",
      "default": ""
    },
    "lead_email": {
      "type": "string",
      "description": "Email do lead",
      "default": ""
    },
    "lead_personalid": {
      "type": "string",
      "description": "Documento de identificação",
      "default": ""
    },
    "lead_status": {
      "type": "string",
      "description": "Status livre do lead",
      "default": ""
    },
    "lead_tags": {
      "type": "array",
      "description": "Tags do lead. Tags configuradas com `kanban=true` também determinam as\ncolunas em que o cartão aparece no Kanban.\n",
      "items": {
        "type": "string"
      }
    },
    "lead_notes": {
      "type": "string",
      "description": "Anotações sobre o lead",
      "default": ""
    },
    "lead_isTicketOpen": {
      "type": "boolean",
      "description": "Indica se tem ticket aberto",
      "default": false
    },
    "lead_assignedAttendant_id": {
      "type": "string",
      "description": "ID do atendente responsável",
      "default": ""
    },
    "lead_kanbanOrder": {
      "type": "integer",
      "format": "int64",
      "description": "Ordem no kanban",
      "default": 0
    },
    "lead_field01": {
      "type": "string",
      "default": ""
    },
    "lead_field02": {
      "type": "string",
      "default": ""
    },
    "lead_field03": {
      "type": "string",
      "default": ""
    },
    "lead_field04": {
      "type": "string",
      "default": ""
    },
    "lead_field05": {
      "type": "string",
      "default": ""
    },
    "lead_field06": {
      "type": "string",
      "default": ""
    },
    "lead_field07": {
      "type": "string",
      "default": ""
    },
    "lead_field08": {
      "type": "string",
      "default": ""
    },
    "lead_field09": {
      "type": "string",
      "default": ""
    },
    "lead_field10": {
      "type": "string",
      "default": ""
    },
    "lead_field11": {
      "type": "string",
      "default": ""
    },
    "lead_field12": {
      "type": "string",
      "default": ""
    },
    "lead_field13": {
      "type": "string",
      "default": ""
    },
    "lead_field14": {
      "type": "string",
      "default": ""
    },
    "lead_field15": {
      "type": "string",
      "default": ""
    },
    "lead_field16": {
      "type": "string",
      "default": ""
    },
    "lead_field17": {
      "type": "string",
      "default": ""
    },
    "lead_field18": {
      "type": "string",
      "default": ""
    },
    "lead_field19": {
      "type": "string",
      "default": ""
    },
    "lead_field20": {
      "type": "string",
      "default": ""
    },
    "chatbot_agentResetMemoryAt": {
      "type": "integer",
      "format": "int64",
      "description": "Início da memória da IA (ms): o agente só lê as mensagens da conversa a partir daqui. 0: sem corte (vale a janela do agente). Grave pelo `/chat/editLead`.",
      "default": 0
    },
    "chatbot_lastTrigger_id": {
      "type": "string",
      "description": "ID do último gatilho executado",
      "default": ""
    },
    "chatbot_lastTriggerAt": {
      "type": "integer",
      "format": "int64",
      "description": "Timestamp do último gatilho",
      "default": 0
    },
    "chatbot_disableUntil": {
      "type": "integer",
      "format": "int64",
      "description": "Automação (IA, gatilhos e fluxos) pausada nesta conversa até este horário, em milissegundos. `-1`: até alguém religar; `0`: ligada.",
      "default": 0
    },
    "chatbot_summary": {
      "type": "string",
      "description": "Motivo da pausa feita pela automação: pedido de humano (IA ou fluxo; pausa até alguém religar) ou limite de respostas da IA (pausa de 1 hora). Vazio quando não há pausa ou depois que ela acaba. Religar (`chatbot_disableUntil: 0` no `/chat/editLead`) ou concluir (`POST /lead/resolve`) limpa.",
      "default": ""
    }
  }
}
```

## Guias relacionados

[Autenticação](/docs/authentication) · [Erros e retries](/docs/errors-and-retries) · [Server URL](/docs/server-url)