WhatsApp

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Instalação (sob demanda)

• O onboarding (openclaw onboard) e openclaw channels add --channel whatsapp solicitam a instalação do plugin do WhatsApp na primeira vez que você o seleciona.
• openclaw channels login --channel whatsapp também oferece o fluxo de instalação quando o plugin ainda não está presente.
• Canal de desenvolvimento + checkout git: usa por padrão o caminho do plugin local.
• Estável/Beta: usa o pacote npm @openclaw/whatsapp na tag de lançamento oficial atual.

openclaw plugins install @openclaw/whatsapp

winget install --id Git.Git -e

​

Configuração rápida

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15551234567"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

openclaw channels login --channel whatsapp

openclaw channels login --channel whatsapp --account work

openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth
openclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

​

Padrões de implantação

{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}

​

Modelo de runtime

• O Gateway gerencia o socket do WhatsApp e o loop de reconexão.
• O watchdog de reconexão usa a atividade de transporte do WhatsApp Web, não apenas o volume de mensagens de aplicativo recebidas, portanto uma sessão silenciosa de dispositivo vinculado não é reiniciada apenas porque ninguém enviou uma mensagem recentemente. Um limite maior de silêncio de aplicação ainda força uma reconexão se frames de transporte continuarem chegando, mas nenhuma mensagem de aplicação for processada durante a janela do watchdog; após uma reconexão transitória para uma sessão recentemente ativa, essa verificação de silêncio de aplicação usa o timeout normal de mensagens para a primeira janela de recuperação.
• Os tempos do socket Baileys são explícitos em web.whatsapp.*: keepAliveIntervalMs controla pings de aplicação do WhatsApp Web, connectTimeoutMs controla o timeout do handshake de abertura, e defaultQueryTimeoutMs controla timeouts de consultas do Baileys.
• Envios de saída exigem um listener ativo do WhatsApp para a conta de destino.
• Envios em grupo anexam metadados nativos de menção para tokens @+<digits> e @<digits> em texto e legendas de mídia quando o token corresponde aos metadados atuais de participantes do WhatsApp, incluindo grupos apoiados por LID.
• Chats de status e broadcast são ignorados (@status, @broadcast).
• O watchdog de reconexão acompanha a atividade de transporte do WhatsApp Web, não apenas o volume de mensagens de aplicativo recebidas: sessões silenciosas de dispositivo vinculado permanecem ativas enquanto frames de transporte continuam, mas uma interrupção de transporte força reconexão bem antes do caminho posterior de desconexão remota.
• Chats diretos usam regras de sessão de DM (session.dmScope; o padrão main consolida DMs na sessão principal do agente).
• Sessões de grupo são isoladas (agent:<agentId>:whatsapp:group:<jid>).
• Canais/Newsletters do WhatsApp podem ser destinos explícitos de saída com seu JID nativo @newsletter. Envios de newsletter de saída usam metadados de sessão de canal (agent:<agentId>:whatsapp:channel:<jid>) em vez da semântica de sessão de DM.
• O transporte do WhatsApp Web respeita variáveis de ambiente padrão de proxy no host do gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / variantes em minúsculas). Prefira configuração de proxy em nível de host em vez de configurações de proxy específicas do canal WhatsApp.
• Quando messages.removeAckAfterReply está ativado, a OpenClaw limpa a reação de confirmação do WhatsApp após uma resposta visível ser entregue.

​

Hooks de plugin e privacidade

{
  channels: {
    whatsapp: {
      pluginHooks: {
        messageReceived: true,
      },
    },
  },
}

{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          pluginHooks: {
            messageReceived: true,
          },
        },
      },
    },
  },
}

​

Controle de acesso e ativação

​

Comportamento de número pessoal e conversa consigo mesmo

• ignorar recibos de leitura para turnos de conversa consigo mesmo
• ignorar comportamento de acionamento automático por JID de menção que, caso contrário, faria ping em você mesmo
• se messages.responsePrefix não estiver definido, respostas de conversa consigo mesmo usam por padrão [{identity.name}] ou [openclaw]

​

Normalização de mensagens e contexto

[Replying to <sender> id:<stanzaId>]
<quoted body or media placeholder>
[/Replying]

{
  channels: {
    whatsapp: {
      sendReadReceipts: false,
    },
  },
}

{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          sendReadReceipts: false,
        },
      },
    },
  },
}

​

Entrega, fragmentação e mídia

​

Citação de resposta

{
  channels: {
    whatsapp: {
      replyToMode: "first",
    },
  },
}

​

Nível de reação

{
  channels: {
    whatsapp: {
      reactionLevel: "ack",
    },
  },
}

​

Reações de confirmação

{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // always | mentions | never
      },
    },
  },
}

• enviadas imediatamente depois que a entrada é aceita (antes da resposta)
• falhas são registradas, mas não bloqueiam a entrega normal da resposta
• o modo de grupo mentions reage em turnos acionados por menção; a ativação de grupo always atua como desvio para essa verificação
• WhatsApp usa channels.whatsapp.ackReaction (o legado messages.ackReaction não é usado aqui)

​

Múltiplas contas e credenciais

​

Ferramentas, ações e gravações de configuração

• O suporte a ferramentas do agente inclui a ação de reação do WhatsApp (react).
• Portões de ação:
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• Gravações de configuração iniciadas pelo canal são ativadas por padrão (desative via channels.whatsapp.configWrites=false).

​

Solução de problemas

openclaw channels login --channel whatsapp
openclaw channels status

{
  web: {
    whatsapp: {
      keepAliveIntervalMs: 15000,
      connectTimeoutMs: 60000,
      defaultQueryTimeoutMs: 60000,
    },
  },
}

openclaw doctor
openclaw logs --follow

​

Prompts do sistema

1. Prompt do sistema específico do grupo (groups["<groupId>"].systemPrompt): usado quando a entrada do grupo específico existe no mapa e sua chave systemPrompt está definida. Se systemPrompt for uma string vazia (""), o curinga é suprimido e nenhum prompt do sistema é aplicado.
2. Prompt do sistema curinga de grupo (groups["*"].systemPrompt): usado quando a entrada do grupo específico está totalmente ausente do mapa ou quando ela existe, mas não define uma chave systemPrompt.

1. Prompt de sistema específico de direct (direct["<peerId>"].systemPrompt): usado quando a entrada do par específico existe no mapa e sua chave systemPrompt está definida. Se systemPrompt for uma string vazia (""), o curinga será suprimido e nenhum prompt de sistema será aplicado.
2. Prompt de sistema curinga de direct (direct["*"].systemPrompt): usado quando a entrada do par específico está totalmente ausente do mapa, ou quando ela existe, mas não define nenhuma chave systemPrompt.

• channels.whatsapp.groups é ao mesmo tempo um mapa de configuração por grupo e a allowlist de grupos no nível do chat. No escopo raiz ou no escopo da conta, groups["*"] significa “todos os grupos são admitidos” para esse escopo.
• Adicione um systemPrompt de grupo curinga somente quando você já quiser que esse escopo admita todos os grupos. Se você ainda quiser que apenas um conjunto fixo de IDs de grupo seja elegível, não use groups["*"] como padrão de prompt. Em vez disso, repita o prompt em cada entrada de grupo explicitamente permitida.
• A admissão de grupos e a autorização de remetentes são verificações separadas. groups["*"] amplia o conjunto de grupos que podem chegar ao tratamento de grupos, mas por si só não autoriza todos os remetentes nesses grupos. O acesso do remetente ainda é controlado separadamente por channels.whatsapp.groupPolicy e channels.whatsapp.groupAllowFrom.
• channels.whatsapp.direct não tem o mesmo efeito colateral para DMs. direct["*"] fornece apenas uma configuração padrão de chat direct depois que uma DM já foi admitida por dmPolicy mais allowFrom ou regras do armazenamento de pareamento.

{
  channels: {
    whatsapp: {
      groups: {
        // Use only if all groups should be admitted at the root scope.
        // Applies to all accounts that do not define their own groups map.
        "*": { systemPrompt: "Default prompt for all groups." },
      },
      direct: {
        // Applies to all accounts that do not define their own direct map.
        "*": { systemPrompt: "Default prompt for all direct chats." },
      },
      accounts: {
        work: {
          groups: {
            // This account defines its own groups, so root groups are fully
            // replaced. To keep a wildcard, define "*" explicitly here too.
            "120363406415684625@g.us": {
              requireMention: false,
              systemPrompt: "Focus on project management.",
            },
            // Use only if all groups should be admitted in this account.
            "*": { systemPrompt: "Default prompt for work groups." },
          },
          direct: {
            // This account defines its own direct map, so root direct entries are
            // fully replaced. To keep a wildcard, define "*" explicitly here too.
            "+15551234567": { systemPrompt: "Prompt for a specific work direct chat." },
            "*": { systemPrompt: "Default prompt for work direct chats." },
          },
        },
      },
    },
  },
}

​

Ponteiros da referência de configuração

• Referência de configuração - WhatsApp

• acesso: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• entrega: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
• multi-account: accounts.<id>.enabled, accounts.<id>.authDir, substituições no nível da conta
• operações: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*, web.whatsapp.*
• comportamento da sessão: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit
• prompts: groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt

​

Relacionado

• Pareamento
• Grupos
• Segurança
• Roteamento de canais
• Roteamento multiagente
• Solução de problemas