Este serviço utiliza a capacidade de dispositivos vinculados do WhatsApp, e não a API Business oficial do WhatsApp; a forma de conexão da conta não é suportada oficialmente pelo WhatsApp. Alterações de protocolo, revogação de dispositivo ou restrições de conta podem causar interrupções. Conecte apenas contas que você possui, cumpra os termos do WhatsApp e não use para mensagens de spam ou envios em massa sem consentimento.
Implantação e autorização pessoal
- Crie o aplicativo «Proxy de conta do WhatsApp» no console, ative a assinatura e clique em implantar. Os recursos da instância são configurados automaticamente pela plataforma.
- Depois que a instância estiver pronta, veja o código QR na página de gerenciamento. Abra o WhatsApp no seu celular e acesse Configurações → Dispositivos conectados → Conectar um dispositivo para escaneá-lo. Você também pode inserir seu próprio número de celular para solicitar um código de pareamento e depois confirmá-lo no celular.
- Depois que o status na página de gerenciamento mudar para «Conectado», copie o endereço MCP exclusivo e o token de acesso Bearer.
- Sair da conta tentará revogar o dispositivo conectado e limpar a sessão local e o histórico. Se o resultado da saída for incerto, primeiro revogue esse dispositivo em «Dispositivos conectados» no celular; destruir a instância removerá seu volume persistente.
Autenticação e capacidades
Exceto por/health e /readyz, as interfaces REST, MCP, de escaneamento e de pareamento exigem Authorization: Bearer <token de acesso>. Coloque o token apenas no cabeçalho da solicitação, não na URL ou nos logs. GET /api/capabilities apresenta as operações realmente suportadas pela instância atual e os limites de retenção.
Atualmente há suporte para: status da conta e da conexão, conversas e contatos sincronizados com o dispositivo conectado, eventos de mensagens em tempo real, leitura de mensagens armazenadas localmente, envio e recebimento de texto e mídia de até 10 MiB, respostas com citação, reações com emoji, marcação como lido, bem como edição/revogação de mensagens próprias, informações de grupo e operações de membro único permitidas pelas permissões da conta e pelas regras atuais do WhatsApp. As alterações de grupo continuam sendo validadas pelo WhatsApp quanto às permissões de membros e administradores.
Escopo do histórico: só é possível ler as mensagens efetivamente sincronizadas do celular para o dispositivo conectado, bem como as mensagens recebidas enquanto o proxy está online. Não é possível garantir a obtenção de todas as mensagens antigas; localmente, são mantidas no máximo as 5.000 mensagens e os 2.000 eventos mais recentes. Quando os metadados de mídia existem, a mídia original também pode já não estar disponível para download.
MCP
A página de gerenciamento da implantação fornecehttps://whatsapp-bot-<ID da instância>.app.acedata.cloud/mcp. Configure esse endereço em um cliente MCP que suporte Streamable HTTP e cabeçalhos de solicitação personalizados, e adicione o mesmo token Bearer. As ferramentas MCP incluem whatsapp_capabilities, whatsapp_whoami, whatsapp_chats, whatsapp_contacts, whatsapp_messages, whatsapp_events, whatsapp_send, whatsapp_send_status, whatsapp_media, whatsapp_mark_read, whatsapp_group e whatsapp_group_update.
O Agent pode ler mensagens conforme suas próprias tarefas; antes de enviar mensagens a terceiros, alterar mensagens ou modificar grupos, deve pedir que o usuário confirme o destinatário específico e o conteúdo. Configurar o MCP não acionará nenhum envio por conta própria.
Exemplos REST
target deve usar o JID retornado por /api/chats ou /api/contacts; não é permitido usar números de telefone arbitrários para envio a frio. Primeiro, peça ao titular que confirme o destinatário e o conteúdo.
action pode ser text, media, edit, revoke ou reaction. Para envio de mídia, passe media_base64 e mime_type; para respostas, passe reply_to; para edição e revogação, passe o message_id próprio que pode ser localizado localmente; para reações, passe message_id e emoji. É possível baixar mídia por meio de GET /api/chats/{target}/messages/{id}/media e marcar como lido por meio de POST /api/chats/{target}/read.
O envio deve incluir uma Idempotency-Key de 8 a 128 caracteres. O message_id retornado é fixo, e o status será pending, accepted, unknown, delivered ou read. accepted significa apenas que a conexão local aceitou o envio, não significa que o destinatário o recebeu. Quando ocorrer unknown, consulte GET /api/sends/{Idempotency-Key} e os eventos de mensagem; não use uma nova chave para enviar novamente a mesma mensagem, a fim de evitar duplicações. O proxy não reenviará automaticamente operações incertas.
Os registros de envio não são eliminados automaticamente; ao atingir 100.000 registros, a instância rejeita novos envios (HTTP 507), evitando envios duplicados após chaves de idempotência antigas serem limpas.
Eventos em tempo real
GET /api/events?after=<último next_cursor>&wait_ms=25000 oferece suporte a long polling de até 25 segundos; GET /api/events/stream?after=<cursor> fornece SSE. Os eventos incluem seq monotonicamente crescente. O next_cursor na resposta deve ser salvo no estado persistente do Agent; se gap=true, isso indica que eventos antigos foram limpos, devendo-se buscar novamente o estado atual das conversas e continuar a partir de oldest_cursor. Eventos de mensagem, status de envio e status de conexão são reportados de forma independente.
Status comuns
Não é garantido histórico ilimitado, disponibilidade de longo prazo de todas as mídias, nem que todas as operações de grupo sejam sempre aceitas pelo WhatsApp. Ao precisar verificar uma instância específica, consulte primeiro
/api/auth/status e /api/capabilities.