API de Usuários

Documentação completa dos endpoints para gerenciar perfil, contatos e privacidade.

📋 Índice

Informações do Usuário
Verificar Usuário no WhatsApp
Avatar do Usuário
Listar Contatos
Privacidade
- Consultar Privacidade
- Configurar Privacidade
Bloqueio de Contatos
Perfil

Informações do Usuário

Obtém informações detalhadas de um ou mais usuários WhatsApp.

Endpoint: POST /user/info

Headers:

Content-Type: application/json
apikey: SUA-CHAVE-API

Body:

{
  "number": ["5511999999999", "5511888888888"]
}

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
`number`	array	✅ Sim	Array de números a consultar

Resposta de Sucesso (200):

{
  "message": "success",
  "data": {
    "Users": {
      "5511999999999@s.whatsapp.net": {
        "VerifiedName": {
          "Certificate": {...},
          "Details": {
            "Serial": 123,
            "Issuer": "WhatsApp",
            "VerifiedName": "Empresa Verificada LTDA"
          }
        },
        "Status": "Olá! Estou usando WhatsApp.",
        "PictureID": "abc123",
        "Devices": ["5511999999999.0:1@s.whatsapp.net"],
        "LID": "lid_string"
      }
    }
  }
}

Campos da Resposta:

VerifiedName: Nome verificado (empresas) ou null
Status: Recado/status do usuário
PictureID: ID da foto de perfil
Devices: Lista de dispositivos conectados
LID: Local ID (se disponível)

Exemplo cURL:

curl -X POST http://localhost:4000/user/info \
  -H "Content-Type: application/json" \
  -H "apikey: SUA-CHAVE-API" \
  -d '{
    "number": ["5511999999999"]
  }'

Verificar Usuário no WhatsApp

Verifica se um número existe no WhatsApp e retorna o JID correto para mensagens.

Endpoint: POST /user/check

Body:

{
  "number": ["5511999999999", "11999999999", "+55 11 99999-9999"],
  "formatJid": false
}

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
`number`	array	✅ Sim	Array de números em qualquer formato
`formatJid`	bool	❌ Não	Formatar número (padrão: false)

Nota Importante: Por padrão, formatJid=false para verificação. O sistema tenta automaticamente ambos os formatos se o primeiro falhar.

Resposta de Sucesso (200):

{
  "message": "success",
  "data": {
    "Users": [
      {
        "Query": "5511999999999",
        "IsInWhatsapp": true,
        "JID": "5511999999999@s.whatsapp.net",
        "RemoteJID": "5511999999999@s.whatsapp.net",
        "LID": "lid_string",
        "VerifiedName": "Empresa LTDA"
      },
      {
        "Query": "5511888888888",
        "IsInWhatsapp": false,
        "JID": "",
        "RemoteJID": "5511888888888",
        "LID": null,
        "VerifiedName": ""
      }
    ]
  }
}

Campos da Resposta:

Query: Número original consultado
IsInWhatsapp: Se existe no WhatsApp
JID: JID do usuário (vazio se não existe)
RemoteJID: JID recomendado para envio de mensagens
LID: Local ID
VerifiedName: Nome verificado (empresas)

Exemplo cURL:

curl -X POST http://localhost:4000/user/check \
  -H "Content-Type: application/json" \
  -H "apikey: SUA-CHAVE-API" \
  -d '{
    "number": ["5511999999999", "11888888888"]
  }'

Avatar do Usuário

Obtém a URL da foto de perfil de um usuário.

Endpoint: POST /user/avatar

Body:

{
  "number": "5511999999999",
  "preview": false
}

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
`number`	string	✅ Sim	Número do usuário
`preview`	bool	❌ Não	Se true, retorna preview (menor resolução)

Resposta de Sucesso (200):

{
  "message": "success",
  "data": {
    "URL": "https://pps.whatsapp.net/v/...",
    "ID": "abc123",
    "Type": "image",
    "DirectPath": "/v/..."
  }
}

Resposta de Erro (500):

{
  "error": "no profile picture found"
}

Exemplo cURL:

curl -X POST http://localhost:4000/user/avatar \
  -H "Content-Type: application/json" \
  -H "apikey: SUA-CHAVE-API" \
  -d '{
    "number": "5511999999999",
    "preview": true
  }'

Listar Contatos

Obtém todos os contatos salvos na conta WhatsApp.

Endpoint: GET /user/contacts

Headers:

apikey: SUA-CHAVE-API

Resposta de Sucesso (200):

{
  "message": "success",
  "data": [
    {
      "Jid": "5511999999999@s.whatsapp.net",
      "Found": true,
      "FirstName": "João",
      "FullName": "João Silva",
      "PushName": "João",
      "BusinessName": ""
    },
    {
      "Jid": "5511888888888@s.whatsapp.net",
      "Found": true,
      "FirstName": "Maria",
      "FullName": "Maria Santos",
      "PushName": "Maria",
      "BusinessName": "Loja da Maria"
    }
  ]
}

Campos da Resposta:

Jid: JID do contato
Found: Se foi encontrado no WhatsApp
FirstName: Primeiro nome
FullName: Nome completo
PushName: Nome exibido no WhatsApp
BusinessName: Nome da empresa (se for conta comercial)

Exemplo cURL:

curl -X GET http://localhost:4000/user/contacts \
  -H "apikey: SUA-CHAVE-API"

Privacidade

Consultar Privacidade

Obtém as configurações atuais de privacidade da conta.

Endpoint: GET /user/privacy

Headers:

apikey: SUA-CHAVE-API

Resposta de Sucesso (200):

{
  "message": "success",
  "data": {
    "GroupAdd": "all",
    "LastSeen": "contacts",
    "Status": "contacts",
    "Profile": "all",
    "ReadReceipts": "all",
    "CallAdd": "all",
    "Online": "all"
  }
}

Valores Possíveis:

all - Todos
contacts - Apenas contatos
contact_blacklist - Meus contatos exceto...
none - Ninguém
match_last_seen - Mesmo de "Visto por último"

Exemplo cURL:

curl -X GET http://localhost:4000/user/privacy \
  -H "apikey: SUA-CHAVE-API"

Configurar Privacidade

Define as configurações de privacidade da conta.

Endpoint: POST /user/privacy

Body:

{
  "groupAdd": "contacts",
  "lastSeen": "contacts",
  "status": "contacts",
  "profile": "all",
  "readReceipts": "all",
  "callAdd": "all",
  "online": "all"
}

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
`groupAdd`	string	✅ Sim	Quem pode me adicionar em grupos
`lastSeen`	string	✅ Sim	Quem vê meu "visto por último"
`status`	string	✅ Sim	Quem vê meu recado/status
`profile`	string	✅ Sim	Quem vê minha foto de perfil
`readReceipts`	string	✅ Sim	Confirmações de leitura
`callAdd`	string	✅ Sim	Quem pode me ligar
`online`	string	✅ Sim	Quem vê quando estou online

Valores Permitidos: all, contacts, contact_blacklist, none, match_last_seen

Resposta de Sucesso (200):

{
  "message": "success",
  "data": {
    "GroupAdd": "contacts",
    "LastSeen": "contacts",
    "Status": "contacts",
    "Profile": "all",
    "ReadReceipts": "all",
    "CallAdd": "all",
    "Online": "all"
  }
}

Exemplo cURL:

curl -X POST http://localhost:4000/user/privacy \
  -H "Content-Type: application/json" \
  -H "apikey: SUA-CHAVE-API" \
  -d '{
    "groupAdd": "contacts",
    "lastSeen": "contacts",
    "status": "contacts",
    "profile": "all",
    "readReceipts": "all",
    "callAdd": "all",
    "online": "all"
  }'

Bloqueio de Contatos

Bloquear Contato

Bloqueia um contato no WhatsApp.

Endpoint: POST /user/block

Body:

{
  "number": "5511999999999"
}

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
`number`	string	✅ Sim	Número do contato a bloquear

Resposta de Sucesso (200):

{
  "message": "success",
  "data": {
    "DHash": "abc123",
    "PrevDHash": "def456",
    "Modifications": [
      {
        "JID": "5511999999999@s.whatsapp.net",
        "Action": "block"
      }
    ]
  }
}

Exemplo cURL:

curl -X POST http://localhost:4000/user/block \
  -H "Content-Type: application/json" \
  -H "apikey: SUA-CHAVE-API" \
  -d '{
    "number": "5511999999999"
  }'

Desbloquear Contato

Desbloqueia um contato previamente bloqueado.

Endpoint: POST /user/unblock

Body:

{
  "number": "5511999999999"
}

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
`number`	string	✅ Sim	Número do contato a desbloquear

Resposta de Sucesso (200):

{
  "message": "success",
  "data": {
    "DHash": "abc123",
    "PrevDHash": "def456",
    "Modifications": [
      {
        "JID": "5511999999999@s.whatsapp.net",
        "Action": "unblock"
      }
    ]
  }
}

Exemplo cURL:

curl -X POST http://localhost:4000/user/unblock \
  -H "Content-Type: application/json" \
  -H "apikey: SUA-CHAVE-API" \
  -d '{
    "number": "5511999999999"
  }'

Listar Bloqueados

Obtém a lista de todos os contatos bloqueados.

Endpoint: GET /user/blocklist

Headers:

apikey: SUA-CHAVE-API

Resposta de Sucesso (200):

{
  "message": "success",
  "data": {
    "DHash": "abc123",
    "Modifications": [
      {
        "JID": "5511999999999@s.whatsapp.net",
        "Action": "block"
      },
      {
        "JID": "5511888888888@s.whatsapp.net",
        "Action": "block"
      }
    ]
  }
}

Exemplo cURL:

curl -X GET http://localhost:4000/user/blocklist \
  -H "apikey: SUA-CHAVE-API"

Perfil

Alterar Foto de Perfil

Define a foto de perfil da conta WhatsApp.

Endpoint: POST /user/profilePicture

Body:

{
  "image": "https://exemplo.com/foto.jpg"
}

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
`image`	string	✅ Sim	URL da imagem

Nota: A imagem deve ser acessível via HTTP/HTTPS. Formatos aceitos: JPG, PNG.

Resposta de Sucesso (200):

{
  "message": "success",
  "data": {
    "image": "https://exemplo.com/foto.jpg"
  }
}

Exemplo cURL:

curl -X POST http://localhost:4000/user/profilePicture \
  -H "Content-Type: application/json" \
  -H "apikey: SUA-CHAVE-API" \
  -d '{
    "image": "https://exemplo.com/minha-foto.jpg"
  }'

Alterar Nome

Define o nome de exibição da conta WhatsApp.

Endpoint: POST /user/profileName

Body:

{
  "name": "João Silva"
}

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
`name`	string	✅ Sim	Novo nome de exibição

Resposta de Sucesso (200):

{
  "message": "success",
  "data": {
    "name": "João Silva"
  }
}

Exemplo cURL:

curl -X POST http://localhost:4000/user/profileName \
  -H "Content-Type: application/json" \
  -H "apikey: SUA-CHAVE-API" \
  -d '{
    "name": "Meu Novo Nome"
  }'

Alterar Status/Recado

Define o recado (status) da conta WhatsApp.

Endpoint: POST /user/profileStatus

Body:

{
  "status": "Disponível para atendimento 24h!"
}

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
`status`	string	✅ Sim	Novo recado/status

Resposta de Sucesso (200):

{
  "message": "success",
  "data": {
    "status": "Disponível para atendimento 24h!"
  }
}

Exemplo cURL:

curl -X POST http://localhost:4000/user/profileStatus \
  -H "Content-Type: application/json" \
  -H "apikey: SUA-CHAVE-API" \
  -d '{
    "status": "Olá! Como posso ajudar?"
  }'

Casos de Uso Comuns

Validar Números Antes de Enviar

Sempre verifique se o número existe antes de tentar enviar mensagem:

# 1. Verificar número
curl -X POST http://localhost:4000/user/check \
  -H "Content-Type: application/json" \
  -H "apikey: SUA-CHAVE-API" \
  -d '{
    "number": ["5511999999999"]
  }'

# 2. Se IsInWhatsapp=true, use RemoteJID para enviar
curl -X POST http://localhost:4000/send/text \
  -H "Content-Type: application/json" \
  -H "apikey: SUA-CHAVE-API" \
  -d '{
    "number": "5511999999999@s.whatsapp.net",
    "text": "Olá!",
    "formatJid": false
  }'

Configurar Privacidade Máxima

curl -X POST http://localhost:4000/user/privacy \
  -H "Content-Type: application/json" \
  -H "apikey: SUA-CHAVE-API" \
  -d '{
    "groupAdd": "contacts",
    "lastSeen": "none",
    "status": "contacts",
    "profile": "contacts",
    "readReceipts": "all",
    "callAdd": "contacts",
    "online": "none"
  }'

Personalizar Perfil Completo

# 1. Foto de perfil
curl -X POST http://localhost:4000/user/profilePicture \
  -H "Content-Type: application/json" \
  -H "apikey: SUA-CHAVE-API" \
  -d '{"image": "https://exemplo.com/logo.jpg"}'

# 2. Nome
curl -X POST http://localhost:4000/user/profileName \
  -H "Content-Type: application/json" \
  -H "apikey: SUA-CHAVE-API" \
  -d '{"name": "Empresa LTDA"}'

# 3. Status
curl -X POST http://localhost:4000/user/profileStatus \
  -H "Content-Type: application/json" \
  -H "apikey: SUA-CHAVE-API" \
  -d '{"status": "Atendimento 24h - (11) 99999-9999"}'

Códigos de Erro Comuns

Código	Erro	Solução
400	`phone number is required`	Forneça o campo `number`
400	`image is required`	Forneça uma URL de imagem válida
500	`instance not found`	Instância não conectada
500	`no profile picture found`	Usuário não tem foto de perfil
500	`invalid phone number`	Formato de número inválido

Boas Práticas

1. Cache de Verificações

Evite verificar o mesmo número múltiplas vezes. Implemente um sistema de cache na sua aplicação:

Armazene o resultado da verificação por algumas horas
Antes de chamar a API, verifique se já tem o resultado em cache
Isso reduz requisições desnecessárias e melhora a performance

2. Privacidade Responsável

Configure privacidade adequada para contas comerciais:

readReceipts: all - Envie confirmações de leitura
online: contacts - Evite mostrar online para todos
groupAdd: contacts - Evite spam de grupos

3. Validação de Imagens

Ao alterar foto de perfil, certifique-se que a imagem:

Está acessível publicamente (HTTP/HTTPS)
É JPG ou PNG
Tem tamanho adequado (recomendado: 640x640px)

Próximos Passos

API de Mensagens - Enviar e gerenciar mensagens
API de Grupos - Gerenciar grupos WhatsApp
API de Chats - Gerenciar conversas
Visão Geral da API

Documentação gerada para Evolution GO v1.0

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API de Usuários

📋 Índice

Informações do Usuário

Verificar Usuário no WhatsApp

Avatar do Usuário

Listar Contatos

Privacidade

Consultar Privacidade

Configurar Privacidade

Bloqueio de Contatos

Bloquear Contato

Desbloquear Contato

Listar Bloqueados

Perfil

Alterar Foto de Perfil

Alterar Nome

Alterar Status/Recado

Casos de Uso Comuns

Validar Números Antes de Enviar

Configurar Privacidade Máxima

Personalizar Perfil Completo

Códigos de Erro Comuns

Boas Práticas

1. Cache de Verificações

2. Privacidade Responsável

3. Validação de Imagens

Próximos Passos

FilesExpand file tree

api-user.md

Latest commit

History

api-user.md

File metadata and controls

API de Usuários

📋 Índice

Informações do Usuário

Verificar Usuário no WhatsApp

Avatar do Usuário

Listar Contatos

Privacidade

Consultar Privacidade

Configurar Privacidade

Bloqueio de Contatos

Bloquear Contato

Desbloquear Contato

Listar Bloqueados

Perfil

Alterar Foto de Perfil

Alterar Nome

Alterar Status/Recado

Casos de Uso Comuns

Validar Números Antes de Enviar

Configurar Privacidade Máxima

Personalizar Perfil Completo

Códigos de Erro Comuns

Boas Práticas

1. Cache de Verificações

2. Privacidade Responsável

3. Validação de Imagens

Próximos Passos