WaliChat WhatsApp API

Automatize o WhatsApp enviando mensagens, resumindo conversas e gerenciando chats usando linguagem natural com assistentes de IA.

GitHub
1

Documentação

MCP WaliChat WhatsApp API Connector NPM Version

🚀 Potencialize sua automação do WhatsApp com IA! Envie mensagens, resuma conversas e gerencie chats usando linguagem natural do seu assistente de IA favorito, como ChatGPT, Claude ou agentes de IA personalizados.

✨ Integre facilmente a WaliChat WhatsApp API com qualquer cliente de IA com MCP, incluindo ChatGPT, VS Code Copilot, Claude Desktop, Cursor, Windsurf e muitos outros!

💬 Transforme a forma como você se comunica - automatize respostas, analise padrões de conversa e gerencie conversas com clientes em escala, gerencie chats e grupos do WhatsApp, tudo por meio de texto conversacional simples ou comandos de voz com seu assistente de IA.

⚠️ Nota: Você só precisa usar este pacote se o seu cliente MCP não suportar HTTP streaming (anteriormente conhecido como conexão SSE). Para usar uma conexão HTTP remota, leia estas instruções.

Conteúdo

Sobre

WaliChat é uma solução versátil de WhatsApp Team Chat e API para mensagens empresariais, permitindo automatizar qualquer coisa no WhatsApp.

Confira a documentação da API e exemplos aqui

Atualização do produto: 🚀 Automatize qualquer coisa no WhatsApp com nossa nova solução No-Code WaliChat Flows ⚡✨

Exemplos de prompts

Converse com suas conversas do WhatsApp a partir de qualquer cliente de IA ou integração com ferramentas de agente.

Aqui estão vários prompts que você pode usar com qualquer assistente de IA para interagir com o WhatsApp por meio do conector MCP WaliChat:

📱 Mensagens Básicas e Comunicação

  • "Envie uma mensagem do WhatsApp para +1234567890 dizendo 'Olá! Como você está hoje?'"
  • "Envie uma mensagem para o contato chamado 'John Smith' com o texto 'Reunião confirmada para as 15h'"
  • "Envie uma mensagem urgente para +44123456789: 'Por favor, me ligue de volta o mais rápido possível'"
  • "Envie uma mensagem do WhatsApp com uma imagem de [URL] para [phone-number]"
  • "Responda à mensagem [message-id] no chat [chat-id] com 'Obrigado pelo seu feedback!'"

📊 Análise de Conversas e Insights

  • "Resuma minhas últimas 10 mensagens do WhatsApp com +1555123456"
  • "Analise o tom da conversa no meu chat com o grupo Marketing Team"
  • "Mostre-me os principais tópicos discutidos na minha conversa com Sarah na última semana"
  • "Conte quantas mensagens recebi hoje de todos os contatos"
  • "Pesquise mensagens contendo 'invoice' no chat [chat-id]"
  • "Gere um relatório de atividade do chat agrupado por dia para este mês"

👥 Gerenciamento de Grupos e Equipes

  • "Crie um grupo do WhatsApp chamado 'Team Updates' com os participantes +1234567890, +0987654321"
  • "Quantos participantes há no grupo do WhatsApp 'Project Team Alpha'?"
  • "Liste todos os membros do meu grupo 'Family Chat'"
  • "Adicione +1234567890 ao grupo do WhatsApp [group-id]"
  • "Torne +1234567890 administrador do grupo [group-id]"
  • "Obtenha o link de convite para o grupo [group-id]"

⏰ Agendamento de Mensagens e Automação

  • "Agende uma mensagem para +1234567890 dizendo 'Feliz Aniversário!' para ser enviada amanhã às 9h"
  • "Configure uma mensagem de lembrete para o grupo da equipe sobre a reunião na próxima sexta-feira às 14h"
  • "Configure respostas automáticas para mensagens recebidas fora do horário comercial (9h - 17h)"
  • "Crie um fluxo de trabalho: quando alguém enviar 'INFO', envie automaticamente o folheto da nossa empresa"

🔍 Gerenciamento de Contatos e Dispositivos

  • "Verifique se o número de telefone +1555987654 é um número válido do WhatsApp"
  • "Quais números do WhatsApp tenho conectados ao WaliChat?"
  • "Mostre-me o status de todos os meus dispositivos do WhatsApp"
  • "Obtenha as informações de perfil do contato +1234567890"
  • "Mostre-me todos os meus contatos recentes do último mês"

📈 Análises e Relatórios

  • "Gere um relatório dos meus contatos mais frequentes do WhatsApp neste mês"
  • "Mostre-me os dias de conversa mais movimentados do WhatsApp nesta semana"
  • "Qual agente responde mais rápido às consultas dos clientes?"
  • "Mostre-me as tendências de volume de chat nos últimos 30 dias"
  • "Conte mensagens não lidas em todos os meus chats"
  • "Encontre clientes que não interagiram nos últimos 60 dias"

🔔 Status e Monitoramento

  • "Verifique o status de entrega da minha última mensagem para +1234567890"
  • "Mostre-me todas as entregas de mensagens com falha de hoje"
  • "Monitore se meu contato +1555123456 leu minhas mensagens recentes"
  • "Publique 'Trabalhando em novos recursos empolgantes!' como meu status do WhatsApp"

🔄 Operações em Massa e Campanhas

  • "Envie o mesmo anúncio para todos os membros do meu grupo 'Team Updates' individualmente"
  • "Transmita uma saudação de feriado para meus 10 números mais contatados"
  • "Crie uma campanha chamada 'Welcome Series' para enviar 'Bem-vindo ao nosso serviço!' para vários contatos"
  • "Inicie a campanha [campaign-id] e verifique seu status de entrega"

🎯 Automação Inteligente de Negócios

  • "Crie uma etiqueta chamada 'VIP Customer' com cor vermelha e aplique-a em chats importantes"
  • "Atribua o chat [chat-id] ao agente [agent-id]"
  • "Mostre-me todos os chats com a etiqueta 'support'"
  • "Analise o sentimento nas conversas de suporte ao cliente e sinalize as negativas"
  • "Gere um relatório CSV de todos os chats com sua última atividade"
  • "Encontre todas as mensagens não lidas nos meus chats do WhatsApp"

🔐 Gerenciamento de Conta e Arquivos

  • "Mostre-me meu uso e limites atuais da conta WaliChat"
  • "Envie uma imagem de [image-url] para usar em mensagens do WhatsApp"
  • "Liste todos os arquivos enviados marcados como 'marketing'"
  • "Exporte todos os contatos do dispositivo [device-id] para JSON"

Esses prompts cobrem cenários reais para empresas que usam o WhatsApp para atendimento ao cliente, marketing, colaboração em equipe e automação por meio da plataforma WaliChat.

Uso com HTTP streaming

Se o seu cliente MCP suportar HTTP streaming (anteriormente conhecido como Server-Sent Events ou transporte SSE), você pode se conectar diretamente ao servidor MCP WaliChat sem instalar este pacote. Este é o método preferido, pois é mais rápido e não requer configuração local.

Clientes Suportados

A maioria dos clientes MCP modernos suporta HTTP streaming, incluindo:

  • Claude Desktop (versões mais recentes)
  • VS Code Copilot com extensão MCP
  • Cursor (v0.48.0+)
  • Windsurf
  • OpenAI Responses API
  • ChatGPT (usuários Pro têm acesso, em breve mais usuários)

Configuração do Claude Desktop

Adicione isto ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "walichat": {
      "type": "http",
      "url": "https://api.wali.chat/mcp?key=YOUR_WALICHAT_API_KEY"
    }
  }
}

Ou usando variáveis de ambiente:

{
  "mcpServers": {
    "walichat": {
      "type": "http",
      "url": "https://api.wali.chat/mcp?key=${WALICHAT_API_KEY}",
      "env": {
        "WALICHAT_API_KEY": "your-api-key-here"
      }
    }
  }
}

Configuração do VS Code Copilot

Nas configurações do VS Code (formato JSON):

{
  "mcp.servers": {
    "walichat": {
      "url": "https://api.wali.chat/mcp?key=YOUR_WALICHAT_API_KEY",
      "transport": "http-streaming"
    }
  }
}

Benefícios do HTTP Streaming

  • ✅ Nenhuma instalação local necessária
  • ✅ Conexão mais rápida
  • ✅ Atualizações automáticas - sempre usa a versão mais recente do servidor
  • ✅ Maior confiabilidade - sem problemas de dependência do Node.js
  • ✅ Configuração mais simples - apenas uma URL

Obtendo Sua Chave de API

  1. Cadastre-se em WaliChat.com
  2. Acesse suas configurações de API
  3. Copie sua chave de API
  4. Substitua YOUR_WALICHAT_API_KEY na configuração acima

Ferramentas MCP Suportadas

O servidor MCP WaliChat fornece ferramentas abrangentes de automação do WhatsApp organizadas em categorias funcionais. Todas as ferramentas usam parâmetros baseados em ações para interações amigáveis com LLMs:

📱 Mensagens e Comunicação Essenciais

  • manage_whatsapp_messages - Envio universal de mensagens com 11 tipos de ação: texto, mídia, localização, contato, enquete, evento, agendada, ao vivo, expirante, agente e mensagens de modelo
  • manage_whatsapp_message_interactions - Interações de mensagem: responder, encaminhar, reação e votação em enquetes
  • get_whatsapp_chat_messages - Recuperação abrangente de mensagens: recentes, pesquisa, intervalo de datas, por remetente, por tipo, por ID, pesquisa avançada, contexto de thread e filtragem de mídia
  • analyze_whatsapp_chat_messages - Análises de mensagens: estatísticas, rastreamento de status de entrega e exportação de dados em vários formatos

💬 Gerenciamento de Chat e Conversas

  • get_whatsapp_chats - Recuperação universal de chats com 9 ações: recentes, não lidos, por status, atribuídos, por tipo de contato, por ID, pesquisa, arquivados e filtragem por intervalo de datas
  • analyze_whatsapp_chats - Análises e exportação de chats com estatísticas abrangentes e recursos de exportação de dados
  • search_whatsapp_chats_by_name - Pesquisa rápida de chats por nome de contato, nome de grupo ou nome de canal

👥 Gerenciamento de Grupos e Equipes

  • manage_whatsapp_groups - Operações completas de grupo: pesquisa, criação, atualização, entrada, saída, gerenciamento de convites com 8 tipos de ação
  • manage_whatsapp_group_participants - Gerenciamento de participantes: adicionar, remover, promover, rebaixar, fluxo de aprovação com 7 tipos de ação
  • manage_whatsapp_team - Gerenciamento de membros da equipe: pesquisa, criação, atualização, exclusão, controle de acesso a dispositivos com 7 tipos de ação
  • manage_whatsapp_departments - Organização de departamentos: listar, criar, atualizar, excluir com atribuições de agentes e personalização visual

📺 Canais e Transmissão

  • manage_whatsapp_channels - Gerenciamento do ciclo de vida do canal: listar, criar, atualizar, pesquisar, entrar, sair, atualizações de imagem com 9 tipos de ação
  • manage_whatsapp_channel_messages - Recuperação de mensagens do canal com filtragem e paginação
  • manage_whatsapp_status - Gerenciamento de Status do WhatsApp (Stories): obter, publicar, agendar com suporte a mídia e agendamento avançado

🔄 Campanhas e Operações em Massa

  • manage_whatsapp_campaigns - Campanhas de mensagens em massa: pesquisa, criação, atualização, início, parada, exclusão com 7 tipos de ação
  • manage_whatsapp_campaign_contacts - Gerenciamento de destinatários da campanha: pesquisar, adicionar, remover contatos com opções de filtragem
  • manage_whatsapp_queue - Controle de fila de mensagens: monitoramento de status, gerenciamento de fila, exclusão em massa com 3 tipos de ação

📱 Gerenciamento de Dispositivos e Contas

  • get_whatsapp_devices - Listagem de dispositivos com filtros avançados: status, sessão, busca, filtro de ativos/online
  • get_whatsapp_device_details - Informações detalhadas do dispositivo: configuração, status da sessão, métricas e insights
  • health_check - Verificação abrangente de saúde do sistema para o servidor MCP e dispositivos WhatsApp conectados

👤 Gerenciamento de Contatos e Etiquetas

  • manage_whatsapp_contacts - Operações CRUD de contatos: listar, obter, criar, atualizar, excluir, operações em lote, gerenciamento de metadados com 8 tipos de ação
  • manage_whatsapp_contact_actions - Bloqueio de contatos: operações de bloqueio e desbloqueio
  • manage_whatsapp_labels - Gerenciamento de etiquetas: listar, criar, atualizar, excluir com organização por código de cores

📁 Gerenciamento de Arquivos e Mídia

  • search_whatsapp_outbound_files - Busca de arquivos enviados com filtros avançados por tipo, tamanho, data, tags e metadados
  • search_whatsapp_chat_files - Busca de arquivos recebidos de conversas do WhatsApp com opções abrangentes de filtragem

🔧 Sistema e Utilitários

  • ping - Teste básico de conectividade com status do servidor e medição de tempo de resposta

📊 Análises e Insights

Todas as ferramentas incluem recursos abrangentes de análise:

  • Rastreamento de entrega de mensagens e estatísticas
  • Análise e relatórios de atividade de conversas
  • Métricas de desempenho do dispositivo e monitoramento
  • Análises de campanhas e rastreamento de sucesso
  • Insights de produtividade da equipe e relatórios

Cada ferramenta suporta filtragem extensiva, paginação, ordenação e recursos de exportação, tornando-as perfeitas tanto para operações manuais quanto para fluxos de trabalho automatizados por meio de assistentes de IA.

Uso

Todos os clientes MCP mais populares (Claude Desktop, VS Code Copilot, Cursor, Windsurf...) usam o seguinte formato de configuração:

{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-walichat",
        "api-key-goes-here"
      ]
    }
  }
}

Cabeçalhos Personalizados

Para ignorar a autenticação ou enviar cabeçalhos personalizados em todas as solicitações ao seu servidor remoto, passe os argumentos de CLI --header:

{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-walichat",
        "${WALICHAT_API}"
      ],
      "env": {
        "WALICHAT_API": "..."
      }
    },
  }
}

Nota: Cursor e Claude Desktop (Windows) têm um bug onde espaços dentro de args não são escapados quando ele invoca npx, o que acaba corrompendo esses valores. Você pode contornar isso usando:

{
  // rest of config...
  "args": [
    "mcp-walichat",
    "${WALICHAT_API}"
  ],
  "env": {
    "WALICHAT_API": "<walichat-api-get-here>"
  }
},

Uso como ferramenta no OpenAI

Veja como você pode usar o servidor MCP WaliChat como uma ferramenta com o cliente JavaScript da OpenAI:

import OpenAI from 'openai';

const walichatKey = process.env.WALICHAT_API_KEY || 'walichat-api-key-here'

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

// Example: Send a WhatsApp message using OpenAI's new Responses API with MCP
const response = await openai.responses.create({
  model: 'o4-mini',
  tools: [
    {
      type: 'mcp',
      server_label: 'walichat',
      server_url: `https://api.wali.chat/mcp?key=${walichatKey}`,
      require_approval: 'never'
    }
  ],
  input: 'Send a WhatsApp message to +1234567890 saying "Hello from AI!"'
});

console.log('Response:', response);

Certifique-se de instalar as dependências necessárias:

npm install openai

E defina suas variáveis de ambiente:

export OPENAI_API_KEY="your-openai-api-key"
export WALICHAT_API_KEY="your-walichat-api-key"

Esta abordagem usa a nova API Responses da OpenAI com integração MCP, que lida automaticamente com descoberta de ferramentas, execução e comunicação com o servidor MCP WaliChat sem exigir configuração manual do cliente MCP.

Flags

  • Se npx estiver produzindo erros, considere adicionar -y como primeiro argumento para aceitar automaticamente a instalação do pacote mcp-walichat.
      "command": "npx",
      "args": [
        "-y"
        "mcp-walichat",
        "API_KEY_GOES_HERE"
      ]
  • Para forçar npx a sempre verificar se há uma versão atualizada de mcp-walichat, adicione a flag @latest:
      "args": [
        "mcp-walichat@latest"
      ]
  • Para alterar em qual porta mcp-walichat escuta um redirecionamento OAuth (por padrão 3334), adicione um argumento adicional após a URL do servidor. Observe que, independentemente da porta especificada, se ela estiver indisponível, uma porta aberta será escolhida aleatoriamente.
      "args": [
        "mcp-walichat",
        "API_KEY_GOES_HERE"
      ]
  • Para habilitar logs detalhados de depuração, adicione a flag --debug. Isso gravará logs detalhados em ~/.mcp-auth/{server_hash}_debug.log com carimbos de data/hora e informações detalhadas sobre o processo de autenticação, conexões e renovação de tokens.
      "args": [
        "mcp-walichat",
        "API_KEY_GOES_HERE",
        "--debug"
      ]

Claude Desktop

Official Docs

In order to add an MCP server to Claude Desktop you need to edit the configuration file located at:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

If it does not exist yet, you may need to enable it under Settings > Developer.

Restart Claude Desktop to pick up the changes in the configuration file. Upon restarting, you should see a hammer icon in the bottom right corner of the input box.

VS Code Extension / Copilot

Official Docs. Add MCP servers through VS Code settings or via the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) by searching for "MCP". Configuration is managed through VS Code's settings interface.

Cursor

Official Docs. The configuration file is located at ~/.cursor/mcp.json.

As of version 0.48.0, Cursor supports unauthed SSE servers directly. If your MCP server is using the official MCP OAuth authorization protocol, you still need to add a "command" server and call mcp-walichat.

Windsurf

Official Docs. The configuration file is located at ~/.codeium/windsurf/mcp_config.json.

Cline

Official Docs. The configuration file is located at ~/.cline/mcp_servers.json.

Continue.dev

Official Docs. The configuration file is located at ~/.continue/config.json. Continue.dev supports MCP servers for enhanced code context and AI-powered development workflows.

Zed Editor

Official Docs. Configure MCP servers in Zed's settings to extend the AI assistant capabilities. Zed provides native MCP integration for seamless development experience.

Jan AI

Official Docs. Jan AI supports MCP servers through its extension system, allowing you to integrate external tools and data sources with local AI models.

Open WebUI

Official MCP Integration. Open WebUI provides MCP support for connecting external tools and services to your self-hosted AI interface, enabling powerful workflow automation.

Sourcegraph Cody

Official Docs. Cody supports MCP integration for enhanced code understanding and AI-assisted development across your entire codebase.

OpenAI Responses API

You can use the WaliChat MCP server as a tool with OpenAI's new Responses API, which provides native MCP integration without requiring manual client setup.

JavaScript Example

import OpenAI from 'openai';

const walichatKey = process.env.WALICHAT_API_KEY || 'your-walichat-api-key';

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

// Send a WhatsApp message using OpenAI's Responses API with MCP
const response = await openai.responses.create({
  model: 'o1-mini',
  tools: [
    {
      type: 'mcp',
      server_label: 'walichat',
      server_url: `https://api.wali.chat/mcp?key=${walichatKey}`,
      require_approval: 'never'
    }
  ],
  input: 'Send a WhatsApp message to +1234567890 saying "Hello from AI!"'
});

console.log('Response:', response);

Python Example

import os
from openai import OpenAI

walichat_key = os.getenv('WALICHAT_API_KEY', 'your-walichat-api-key')

client = OpenAI(
    api_key=os.getenv('OPENAI_API_KEY')
)

# Send a WhatsApp message using OpenAI's Responses API with MCP
response = client.responses.create(
    model='o1-mini',
    tools=[
        {
            'type': 'mcp',
            'server_label': 'walichat',
            'server_url': f'https://api.wali.chat/mcp?key={walichat_key}',
            'require_approval': 'never'
        }
    ],
    input='Send a WhatsApp message to +1234567890 saying "Hello from AI!"'
)

print('Response:', response)

Installation

Make sure to install the required dependencies:

JavaScript:

npm install openai

Python:

pip install openai

Environment Variables

Set your API keys as environment variables:

export OPENAI_API_KEY="your-openai-api-key"
export WALICHAT_API_KEY="your-walichat-api-key"

This approach uses OpenAI's native MCP integration, which automatically handles tool discovery, execution, and communication with the WaliChat MCP server without requiring manual MCP client configuration.

Solução de Problemas

Limpe seu diretório ~/.mcp-auth

mcp-walichat armazena todas as informações de credenciais dentro de ~/.mcp-auth (ou onde quer que seu MCP_REMOTE_CONFIG_DIR aponte). Se você estiver tendo problemas persistentes, tente executar:

rm -rf ~/.mcp-auth

Em seguida, reinicie seu cliente MCP.

Verifique sua versão do Node

Certifique-se de que a versão do Node que você tem instalada seja 18 ou superior. O Claude Desktop usará a versão do Node do seu sistema, mesmo se você tiver uma versão mais recente instalada em outro lugar.

Reinicie o Claude

Ao modificar claude_desktop_config.json, pode ser útil reiniciar completamente o Claude

Certificados VPN

Você pode encontrar problemas se estiver atrás de uma VPN; tente definir a variável de ambiente NODE_EXTRA_CA_CERTS para apontar para o arquivo de certificado CA. Se estiver usando claude_desktop_config.json, isso pode parecer:

{
 "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-walichat",
        "API_KEY_GOES_HERE"
      ],
      "env": {
        "NODE_EXTRA_CA_CERTS": "{your CA certificate file path}.pem"
      }
    }
  }
}

Verifique os logs

  • Siga os logs do Claude Desktop em tempo real
  • MacOS / Linux:
    tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
  • Para bash no WSL:
    tail -n 20 -f "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log"
  • Powershell:
    Get-Content "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log" -Wait -Tail 20

Depuração

Logs de Depuração

Para solucionar problemas complexos, especialmente com renovação de tokens ou problemas de autenticação, use a flag --debug:

"args": [
  "mcp-walichat",
  "API_KEY_GOES_HERE",
  "--debug"
]

Isso cria logs detalhados em ~/.mcp-auth/{server_hash}_debug.log com carimbos de data/hora e informações completas sobre cada etapa do processo de conexão e autenticação. Quando você encontrar problemas com renovação de tokens, problemas de suspensão/retomada do laptop ou problemas de autenticação, forneça esses logs ao buscar suporte.

Erros de Autenticação

Se você encontrar o seguinte erro, retornado pela URL /callback:

Authentication Error
Token exchange failed: HTTP 400

Você pode executar rm -rf ~/.mcp-auth para limpar qualquer estado e tokens armazenados localmente.

Modo "Cliente"

Execute o seguinte na linha de comando (não de um servidor MCP):

npx -p mcp-walichat@latest mcp-walichat-client API_KEY_GOES_HERE

Isso executará todo o fluxo de autorização e tentará listar as ferramentas e recursos na URL remota. Tente isso após executar rm -rf ~/.mcp-auth para ver se credenciais desatualizadas são o seu problema; caso contrário, esperamos que o problema fique mais óbvio nesses logs do que nos do seu cliente MCP.

Licença

MIT