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
[
{
"token": []
}
]
{
"token": {
"name": "token",
"type": "apiKey",
"in": "header"
}
}
Corpo da requisição
{
"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
{
"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
{
"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": ""
}
}
}