# Documentação das Ferramentas - MCP WPPConnect Server
Este documento descreve detalhadamente todas as ferramentas disponíveis no MCP WPPConnect Server.
## 📋 Índice de Ferramentas
### Gerenciamento de Sessão
1. [initialize_session](#initialize_session)
2. [get_qr_snapshot](#get_qr_snapshot)
3. [get_session_status](#get_session_status)
4. [close_session](#close_session)
### Mensagens
5. [send_text](#send_text)
### Grupos
6. [promote_group_participant](#promote_group_participant)
7. [demote_group_participant](#demote_group_participant)
### Comunidades
8. [get_community_participants](#get_community_participants)
9. [promote_community_participant](#promote_community_participant)
10. [demote_community_participant](#demote_community_participant)
### Utilidades
11. [get_contacts](#get_contacts)
12. [get_chats](#get_chats)
---
## 🔧 Ferramentas de Gerenciamento de Sessão
### initialize_session
**Descrição**: Inicializa uma nova sessão WhatsApp e gera um QR code para autenticação.
**Parâmetros**:
```typescript
{
sessionId: string; // ID único da sessão (mínimo 3 caracteres)
}
```
**Retorno de Sucesso**:
```json
{
"ok": true,
"sessionId": "minha-sessao-1",
"status": "qr_pending",
"message": "Sessão inicializada. Escaneie o QR code para autenticar."
}
```
**Retorno de Erro**:
```json
{
"ok": false,
"error": "Mensagem de erro detalhada"
}
```
**Exemplo de Uso**:
```json
{
"tool": "initialize_session",
"arguments": {
"sessionId": "sessao-negocios"
}
}
```
---
### get_qr_snapshot
**Descrição**: Obtém o QR code atual para uma sessão aguardando autenticação.
**Parâmetros**:
```typescript
{
sessionId: string; // ID da sessão
}
```
**Retorno de Sucesso**:
```json
{
"ok": true,
"sessionId": "minha-sessao-1",
"qrCode": "data:image/png;base64,iVBORw0KGgoAAAANS...",
"status": "qr_pending"
}
```
**Retorno de Erro**:
```json
{
"ok": false,
"error": "QR code não disponível ou sessão já autenticada"
}
```
**Exemplo de Uso**:
```json
{
"tool": "get_qr_snapshot",
"arguments": {
"sessionId": "sessao-negocios"
}
}
```
---
### get_session_status
**Descrição**: Obtém o status atual de uma sessão WhatsApp.
**Parâmetros**:
```typescript
{
sessionId: string; // ID da sessão
}
```
**Retorno de Sucesso**:
```json
{
"ok": true,
"sessionId": "minha-sessao-1",
"status": "authenticated",
"authenticated": true,
"user": {
"id": "5511999999999@c.us",
"name": "João Silva"
}
}
```
**Possíveis Status**:
- `qr_pending` - Aguardando escaneamento do QR
- `authenticated` - Sessão autenticada e ativa
- `disconnected` - Sessão desconectada
- `connecting` - Conectando...
**Exemplo de Uso**:
```json
{
"tool": "get_session_status",
"arguments": {
"sessionId": "sessao-negocios"
}
}
```
---
### close_session
**Descrição**: Fecha e limpa uma sessão WhatsApp, desconectando o cliente.
**Parâmetros**:
```typescript
{
sessionId: string; // ID da sessão
}
```
**Retorno de Sucesso**:
```json
{
"ok": true,
"sessionId": "minha-sessao-1",
"message": "Sessão fechada com sucesso"
}
```
**Exemplo de Uso**:
```json
{
"tool": "close_session",
"arguments": {
"sessionId": "sessao-negocios"
}
}
```
---
## 💬 Ferramentas de Mensagens
### send_text
**Descrição**: Envia uma mensagem de texto via WhatsApp.
**Parâmetros**:
```typescript
{
sessionId: string; // Sessão autenticada
to: string; // Número do destinatário (ex: "5511999999999@c.us")
text: string; // Texto da mensagem (máximo 65535 caracteres)
}
```
**Retorno de Sucesso**:
```json
{
"ok": true,
"data": {
"to": "5511999999999@c.us",
"message": "Olá! Como você está?",
"messageId": "true_5511999999999@c.us_A1B2C3D4"
}
}
```
**Formatos de Destinatário**:
- Contato individual: `5511999999999@c.us`
- Grupo: `551199999999-1234567890@g.us`
**Exemplo de Uso**:
```json
{
"tool": "send_text",
"arguments": {
"sessionId": "sessao-negocios",
"to": "5511999999999@c.us",
"text": "Olá! Esta é uma mensagem automática do nosso sistema."
}
}
```
---
## 👥 Ferramentas de Grupos
### promote_group_participant
**Descrição**: Promove um participante do grupo para status de administrador.
**Parâmetros**:
```typescript
{
sessionId: string; // Sessão autenticada
groupId: string; // ID do grupo
participantId: string; // ID do participante
}
```
**Retorno de Sucesso**:
```json
{
"ok": true,
"data": {
"groupId": "551199999999-1234567890@g.us",
"participantId": "5511888888888@c.us",
"message": "Participante promovido a administrador com sucesso"
}
}
```
**Exemplo de Uso**:
```json
{
"tool": "promote_group_participant",
"arguments": {
"sessionId": "sessao-negocios",
"groupId": "551199999999-1234567890@g.us",
"participantId": "5511888888888@c.us"
}
}
```
---
### demote_group_participant
**Descrição**: Remove privilégios de administrador de um participante do grupo.
**Parâmetros**:
```typescript
{
sessionId: string; // Sessão autenticada
groupId: string; // ID do grupo
participantId: string; // ID do participante
}
```
**Retorno de Sucesso**:
```json
{
"ok": true,
"data": {
"groupId": "551199999999-1234567890@g.us",
"participantId": "5511888888888@c.us",
"message": "Administrador removido com sucesso"
}
}
```
**Exemplo de Uso**:
```json
{
"tool": "demote_group_participant",
"arguments": {
"sessionId": "sessao-negocios",
"groupId": "551199999999-1234567890@g.us",
"participantId": "5511888888888@c.us"
}
}
```
---
## 🏘️ Ferramentas de Comunidades
### get_community_participants
**Descrição**: Obtém a lista de participantes de uma comunidade.
**Parâmetros**:
```typescript
{
sessionId: string; // Sessão autenticada
communityId: string; // ID da comunidade
}
```
**Retorno de Sucesso**:
```json
{
"ok": true,
"data": {
"communityId": "551199999999-1234567890@newsletter",
"participants": [
{
"id": "5511888888888@c.us",
"name": "Maria Santos",
"isAdmin": true
},
{
"id": "5511777777777@c.us",
"name": "João Silva",
"isAdmin": false
}
],
"count": 2
}
}
```
**Exemplo de Uso**:
```json
{
"tool": "get_community_participants",
"arguments": {
"sessionId": "sessao-negocios",
"communityId": "551199999999-1234567890@newsletter"
}
}
```
---
### promote_community_participant
**Descrição**: Promove um participante da comunidade para administrador.
**Parâmetros**:
```typescript
{
sessionId: string; // Sessão autenticada
communityId: string; // ID da comunidade
participantId: string; // ID do participante
}
```
**Retorno de Sucesso**:
```json
{
"ok": true,
"data": {
"communityId": "551199999999-1234567890@newsletter",
"participantId": "5511888888888@c.us",
"message": "Participante promovido a administrador da comunidade"
}
}
```
**Exemplo de Uso**:
```json
{
"tool": "promote_community_participant",
"arguments": {
"sessionId": "sessao-negocios",
"communityId": "551199999999-1234567890@newsletter",
"participantId": "5511888888888@c.us"
}
}
```
---
### demote_community_participant
**Descrição**: Remove privilégios de administrador de um participante da comunidade.
**Parâmetros**:
```typescript
{
sessionId: string; // Sessão autenticada
communityId: string; // ID da comunidade
participantId: string; // ID do participante
}
```
**Retorno de Sucesso**:
```json
{
"ok": true,
"data": {
"communityId": "551199999999-1234567890@newsletter",
"participantId": "5511888888888@c.us",
"message": "Administrador removido da comunidade"
}
}
```
**Exemplo de Uso**:
```json
{
"tool": "demote_community_participant",
"arguments": {
"sessionId": "sessao-negocios",
"communityId": "551199999999-1234567890@newsletter",
"participantId": "5511888888888@c.us"
}
}
```
---
## 📇 Ferramentas de Utilidades
### get_contacts
**Descrição**: Obtém a lista de todos os contatos da sessão autenticada.
**Parâmetros**:
```typescript
{
sessionId: string; // Sessão autenticada
}
```
**Retorno de Sucesso**:
```json
{
"ok": true,
"data": {
"contacts": [
{
"id": "5511999999999@c.us",
"name": "João Silva",
"number": "5511999999999"
},
{
"id": "5511888888888@c.us",
"name": "Maria Santos",
"number": "5511888888888"
}
],
"count": 2
}
}
```
**Exemplo de Uso**:
```json
{
"tool": "get_contacts",
"arguments": {
"sessionId": "sessao-negocios"
}
}
```
---
### get_chats
**Descrição**: Obtém a lista de todas as conversas (chats) da sessão autenticada.
**Parâmetros**:
```typescript
{
sessionId: string; // Sessão autenticada
}
```
**Retorno de Sucesso**:
```json
{
"ok": true,
"data": {
"chats": [
{
"id": "5511999999999@c.us",
"name": "João Silva",
"lastMessage": "Olá! Tudo bem?",
"timestamp": 1640995200000
},
{
"id": "551199999999-1234567890@g.us",
"name": "Grupo de Trabalho",
"lastMessage": "Reunião amanhã às 14h",
"timestamp": 1640908800000
}
],
"count": 2
}
}
```
**Exemplo de Uso**:
```json
{
"tool": "get_chats",
"arguments": {
"sessionId": "sessao-negocios"
}
}
```
---
## 🔒 Considerações de Segurança
- **Sessões**: Use IDs de sessão únicos e imprevisíveis
- **Autenticação**: Mantenha sessões autenticadas seguras
- **Limites**: Respeite os limites de rate do WhatsApp
- **Privacidade**: Nunca exponha informações sensíveis em logs
## 🚨 Tratamento de Erros
Todas as ferramentas retornam um objeto com estrutura consistente:
**Sucesso**:
```json
{
"ok": true,
"data": { ... }
}
```
**Erro**:
```json
{
"ok": false,
"error": "Mensagem de erro descritiva"
}
```
## 📞 Suporte
Para problemas com ferramentas específicas:
1. Verifique se a sessão está autenticada
2. Confirme os parâmetros de entrada
3. Consulte os logs do servidor
4. Abra uma issue no GitHub com detalhes do erro
