Guia Completo de Integracao do OpenClaw com WhatsApp

Os codigos de pareamento expiram apos 1 hora , e as solicitacoes pendentes sao limitadas a 3 por canal.

Modo Allowlist

Apenas numeros de telefone listados em channels.whatsapp.allowFrom podem iniciar conversas.

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

Modo Open

Requer que channels.whatsapp.allowFrom inclua "*" .

Nota: Seu numero vinculado do WhatsApp e implicitamente confiavel — mensagens proprias ignoram as verificacoes de dmPolicy e allowFrom .

Confirmacoes de Leitura

Por padrao, o gateway marca as mensagens recebidas do WhatsApp como lidas (ticks azuis) apos serem aceitas.

Desativar globalmente:

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

Desativar por conta:

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

O modo self-chat sempre ignora confirmacoes de leitura.

Suporte a Chat em Grupo

Grupos sao mapeados para sessoes dedicadas. Configure o comportamento de grupo com:

• Politica de grupo: channels.whatsapp.groupPolicy — open , disabled ou allowlist (padrao: allowlist )
• Modos de ativacao:
  • mention (padrao): requer @mencao ou correspondencia de regex
  • always : sempre aciona uma resposta

Alterne a ativacao com um comando exclusivo do proprietario (deve ser uma mensagem isolada):

/activation mention
/activation always

O proprietario e determinado por channels.whatsapp.allowFrom (ou seu E.164 proprio se nao definido).

Contexto do Historico do Grupo

Mensagens recentes nao processadas (padrao 50) sao automaticamente injetadas como contexto:

[Chat messages since your last reply - for context]
...
[Current message - respond to this]

Cada mensagem inclui um sufixo de remetente: [from: Name (+E164)] .

Os metadados do grupo (assunto + participantes) sao armazenados em cache por 5 minutos.

Reacoes de Confirmacao

O WhatsApp pode enviar automaticamente reacoes com emoji para mensagens recebidas ao recebe-las, fornecendo feedback instantaneo antes do bot gerar uma resposta.

{
  "whatsapp": {
    "ackReaction": {
      "emoji": "👀",
      "direct": true,
      "group": "mentions"
    }
  }
}

Opcoes:

• emoji : Emoji para reagir (ex.: "👀", "✅"). Vazio ou omitido desativa o recurso.
• direct (padrao: true ): Enviar reacoes em chats diretos.
• group (padrao: "mentions" ):
  • "always" : Reagir a todas as mensagens do grupo
  • "mentions" : Reagir apenas quando o bot e @mencionado
  • "never" : Nunca reagir em grupos

Substituicao por conta:

{
  "whatsapp": {
    "accounts": {
      "work": {
        "ackReaction": {
          "emoji": "✅",
          "direct": false,
          "group": "always"
        }
      }
    }
  }
}

As reacoes sao enviadas imediatamente ao receber a mensagem, antes dos indicadores de digitacao ou respostas do bot. Falhas sao registradas nos logs, mas nao impedem o bot de responder.

Tratamento de Mensagens

Mensagens Recebidas

• As mensagens chegam via eventos messages.upsert do Baileys
• Chats de status/broadcast sao ignorados
• Chats diretos usam formato E.164; grupos usam group JID
• O contexto de resposta citada e sempre anexado para fornecer contexto da conversa
• Mensagens apenas com midia usam placeholders: <media:image|video|audio|document|sticker>

Mensagens Enviadas

• O texto e dividido em blocos de 4.000 caracteres por padrao (configuravel via channels.whatsapp.textChunkLimit )
• Divisao opcional por quebra de linha: defina channels.whatsapp.chunkMode="newline" para dividir nos limites de paragrafo antes da divisao por tamanho
• Tipos de midia suportados: imagem, video, audio, documento
• O audio e enviado como notas de voz (PTT). Melhores resultados com formato OGG/Opus
• Legenda apenas no primeiro item de midia
• GIFs animados: o WhatsApp espera MP4 com gifPlayback: true para reproducao em loop inline

Limites de Midia

• Limite de midia recebida : 50 MB (configuravel via channels.whatsapp.mediaMaxMb )
• Limite de midia enviada : 5 MB por item (configuravel via agents.defaults.mediaMaxMb )
• Imagens sao auto-otimizadas para JPEG quando abaixo do limite (redimensionamento + varredura de qualidade)
• Midia acima do limite resulta em erro; a resposta com midia recorre a um aviso em texto

Credenciais e Armazenamento

• Credenciais armazenadas em: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
• Backup automatico em creds.json.bak (restaurado em caso de corrupcao)
• Logout: openclaw channels logout (ou --account <id> ) exclui o estado de autenticacao do WhatsApp, mas mantem o oauth.json compartilhado

Suporte a Multiplas Contas

Multiplas contas do WhatsApp podem ser executadas em um unico processo do Gateway. Use identificadores de conta na configuracao:

{
  channels: {
    whatsapp: {
      accounts: {
        personal: { /* configuracoes por conta */ },
        work: { /* configuracoes por conta */ },
      },
    },
  },
}

As configuracoes por conta suportam substituicoes para sendReadReceipts , ackReaction , mediaMaxMb , historyLimit e mais.

Por Que Nao Twilio / WhatsApp Business API?

As versoes iniciais do OpenClaw suportavam a integracao do WhatsApp Business via Twilio, mas ela foi removida porque:

• Numeros do WhatsApp Business nao sao adequados para um assistente pessoal
• A Meta impoe uma janela de resposta de 24 horas — se voce nao respondeu nas ultimas 24 horas, o numero comercial nao pode iniciar novas mensagens
• Uso de alto volume ou "conversacional" aciona bloqueios agressivos, porque contas comerciais nao foram projetadas para mensagens no estilo de assistente pessoal
• Resultado: entrega nao confiavel e bloqueios frequentes

Referencia Rapida de Configuracao

| Chave de Configuracao | Descricao | |---|---| | channels.whatsapp.dmPolicy | Politica de DM: pairing / allowlist / open / disabled | | channels.whatsapp.selfChatMode | Habilitar para configuracao com numero pessoal | | channels.whatsapp.allowFrom | Lista de permissoes de DM (numeros de telefone E.164) | | channels.whatsapp.sendReadReceipts | Confirmacoes de leitura automaticas (padrao: true) | | channels.whatsapp.ackReaction | Reacao automatica ao receber mensagem | | channels.whatsapp.groupPolicy | Politica de grupo: open / disabled / allowlist | | channels.whatsapp.textChunkLimit | Tamanho do bloco de texto de saida (padrao: 4000) | | channels.whatsapp.mediaMaxMb | Limite de midia recebida (padrao: 50 MB) | | channels.whatsapp.configWrites | Permitir gravacoes de configuracao via comando /config | | agents.defaults.mediaMaxMb | Limite de midia enviada (padrao: 5 MB) |

Solucao de Problemas

Nao Vinculado / Login QR Necessario

Sintoma: channels status mostra linked: false ou avisa "Not linked".

Solucao: Execute openclaw channels login no host do gateway e escaneie o codigo QR (WhatsApp > Configuracoes > Dispositivos Conectados).

Vinculado mas Desconectado / Loop de Reconexao

Sintoma: channels status mostra running, disconnected ou avisa "Linked but disconnected".

Solucao: Execute openclaw doctor ou reinicie o gateway. Se persistir, revincule via openclaw channels login e inspecione openclaw logs --follow .

Problemas com Runtime Bun

O Bun nao e recomendado . WhatsApp (Baileys) e Telegram sao instaveis no Bun. Execute o gateway com Node.js .

Comportamento de Reconexao

O gateway usa uma politica de backoff ( web.reconnect ) com initialMs , maxMs , factor , jitter e maxAttempts configuraveis. Se o numero maximo de tentativas for atingido, o monitoramento web para (modo degradado). Um socket desconectado para e requer re-vinculacao.

Proximos Passos

• Guia de integracao com Telegram
• Guia de integracao com Discord
• Documentacao oficial do WhatsApp