Pular para o conteúdo principal

Documentação oficial desta página · v0.20.6

Instalação do LINE

Rode o Hermes Agent como bot do LINE pela API oficial de mensagens (Messaging API) do LINE. O adaptador vive como um plugin de plataforma embutido em plugins/platforms/line/ — sem editar o núcleo, basta habilitar como qualquer outra plataforma.

O LINE é o aplicativo de mensagens dominante no Japão, em Taiwan e na Tailândia. Se os seus usuários moram lá, é assim que eles chegam até você.

Rode hermes gateway setup e escolha LINE para um passo a passo guiado.

Como o bot responde​

ContextoComportamento
Conversa 1:1 (IDs com U)Responde a toda mensagem
Grupo (IDs com C)Responde quando o grupo está na lista de permissões
Sala com vários usuários (IDs com R)Responde quando a sala está na lista de permissões

Texto, imagens, áudio, vídeo, arquivos, figurinhas e localizações de entrada são todos tratados. O texto de saída usa primeiro o token de resposta gratuito (de uso único, janela de ~60s) e recorre à Push API tarifada quando o token já expirou.

Passo 1: crie um canal Messaging API no LINE​

  1. Vá ao LINE Developers Console.
  2. Crie um Provider e, dentro dele, um canal Messaging API.
  3. Na aba Basic settings do canal, copie o Channel secret.
  4. Na aba Messaging API, role até Channel access token (long-lived) e clique em Issue. Copie o token.
  5. Ainda na aba Messaging API, desative também Auto-reply messages e Greeting messages para que eles não briguem com as respostas do seu bot.

Passo 2: exponha a porta do webhook​

O LINE entrega webhooks por HTTPS público. A porta padrão é 8646 — mude com LINE_PORT se precisar.

# Cloudflare Tunnel (recomendado para produção — hostname fixo)
cloudflared tunnel --url http://localhost:8646

# ngrok (bom para desenvolvimento)
ngrok http 8646

# devtunnel
devtunnel create hermes-line --allow-anonymous
devtunnel port create hermes-line -p 8646 --protocol https
devtunnel host hermes-line

Copie a URL https://... — você vai defini-la como URL de webhook logo abaixo. Deixe o túnel rodando durante os testes. Em produção, configure um túnel nomeado fixo do Cloudflare para que a URL do webhook não mude a cada reinício.

Passo 3: configure o Hermes​

Acrescente ao ~/.hermes/.env:

LINE_CHANNEL_ACCESS_TOKEN=SEU_TOKEN_DE_LONGA_DURACAO
LINE_CHANNEL_SECRET=SEU_CHANNEL_SECRET

# Lista de permissões — pelo menos uma destas (ou LINE_ALLOW_ALL_USERS=true para desenvolvimento)
LINE_ALLOWED_USERS=U1234567890abcdef...           # IDs com prefixo U, separados por vírgula
LINE_ALLOWED_GROUPS=C1234567890abcdef...          # IDs de grupo, opcional
LINE_ALLOWED_ROOMS=R1234567890abcdef...           # IDs de sala, opcional

# Obrigatório para envio de imagem / áudio / vídeo — a URL base HTTPS pública
# para a qual o túnel resolve.  Sem ela, send_image/voice/video vão recusar.
LINE_PUBLIC_URL=https://meu-tunel.exemplo.com

Depois, no ~/.hermes/config.yaml:

gateway:
  platforms:
    line:
      enabled: true

É o bastante — a varredura de plugins embutidos em gateway/config.py encontra plugins/platforms/line/ automaticamente. Sem editar o enum Platform.LINE, sem registro em _create_adapter.

Passo 4: defina a URL do webhook​

De volta ao console do LINE:

  1. Abra o seu canal → aba Messaging API.
  2. Em Webhook settings → Webhook URL, cole https://<seu-tunel>/line/webhook (repare no caminho /line/webhook — é onde o adaptador escuta).
  3. Clique em Verify. O LINE faz um ping na URL; você deve ver um 200.
  4. Ligue Use webhook em On.

Passo 5: rode o gateway​

hermes gateway

O log do agente mostra:

LINE: webhook listening on * (all interfaces, IPv4+IPv6):8646/line/webhook (public: https://my-tunnel.example.com)

Adicione o bot como amigo pelo aplicativo do LINE (leia o QR na aba Messaging API do canal) e mande uma mensagem para ele.

Respostas lentas do LLM​

O token de resposta do LINE é de uso único e expira mais ou menos 60 segundos depois do evento de entrada. LLMs lentos não conseguem responder a tempo, o que normalmente forçaria uma chamada paga à Push API.

Quando o LLM ainda está rodando depois de LINE_SLOW_RESPONSE_THRESHOLD segundos (padrão 45), o adaptador consome o token de resposta original para enviar um balão Template Buttons:

🤔 Ainda pensando. Toque abaixo para buscar a resposta quando ela estiver pronta.

[ Obter resposta ]

O usuário toca em Obter resposta quando lhe convém — esse postback entrega um token de resposta novo, que o adaptador usa para enviar a resposta em cache (ainda de graça).

Máquina de estados: PENDING → READY → DELIVERED, mais ERROR para execuções canceladas (o PENDING órfão vira "Run was interrupted before completion." depois de /stop, para que o botão persistente não fique em laço).

Para desativar o botão de postback e sempre cair no Push:

LINE_SLOW_RESPONSE_THRESHOLD=0

Para que o fluxo de postback dispare de forma confiável, silencie o falatório que consumiria o token de resposta antes do limite:

# ~/.hermes/config.yaml
display:
  interim_assistant_messages: false
  platforms:
    line:
      tool_progress: off

Entrega de cron e notificações​

LINE_HOME_CHANNEL=Uxxxxxxxxxxxxxxxxxxxx     # alvo de entrega padrão

Tarefas de cron com deliver: line vão para o LINE_HOME_CHANNEL. O adaptador traz um remetente independente, só de Push, para que as tarefas de cron funcionem mesmo quando o cron roda em um processo separado do gateway.

Referência de variáveis de ambiente​

VariávelObrigatóriaPadrãoDescrição
LINE_CHANNEL_ACCESS_TOKENsim—Token de acesso ao canal, de longa duração
LINE_CHANNEL_SECRETsim—Segredo do canal (verificação de webhook por HMAC-SHA256)
LINE_HOSTnãosem valor (pilha dupla: todas as interfaces, IPv4+IPv6)Host em que o webhook escuta
LINE_PORTnão8646Porta em que o webhook escuta
LINE_PUBLIC_URLpara mídia—URL base HTTPS pública; obrigatória para enviar imagem/voz/vídeo
LINE_ALLOWED_USERSuma delas—IDs de usuário separados por vírgula (prefixo U)
LINE_ALLOWED_GROUPSuma delas—IDs de grupo separados por vírgula (prefixo C)
LINE_ALLOWED_ROOMSuma delas—IDs de sala separados por vírgula (prefixo R)
LINE_ALLOW_ALL_USERSsó em desenvolvimentofalseIgnora a lista de permissões por completo
LINE_HOME_CHANNELnão—Alvo padrão de entrega de cron e notificações
LINE_SLOW_RESPONSE_THRESHOLDnão45Segundos até o botão de postback disparar (0 = desativado)
LINE_PENDING_TEXTnão"🤔 Still thinking…"Texto do balão que acompanha o botão de postback
LINE_BUTTON_LABELnão"Get answer"Rótulo do botão
LINE_DELIVERED_TEXTnão"Already replied ✅"Resposta quando um botão já entregue é tocado de novo
LINE_INTERRUPTED_TEXTnão"Run was interrupted before completion."Resposta quando um botão órfão de /stop é tocado

Solução de problemas​

"invalid signature" na verificação do webhook. O Channel secret foi copiado errado, ou o seu túnel reescreveu o corpo da requisição. Confira antes com curl -i https://<tunel>/line/webhook/health — isso deve devolver {"status":"ok","platform":"line"}.

O bot não recebe nada em grupos. Verifique se LINE_ALLOWED_GROUPS inclui o ID C... do grupo. Para descobrir o ID de um grupo, mande uma mensagem de teste e procure em ~/.hermes/logs/gateway.log por LINE: rejecting unauthorized source — o dicionário da origem rejeitada traz os IDs.

send_image falha com "LINE_PUBLIC_URL must be set". A Messaging API do LINE não aceita upload binário — imagens, áudio e vídeo precisam ser URLs HTTPS acessíveis. Defina LINE_PUBLIC_URL com o hostname público do túnel e o adaptador serve os arquivos em /line/media/<token>/<nome-do-arquivo> automaticamente.

O botão de postback nunca aparece. Ou o LLM respondeu mais rápido que LINE_SLOW_RESPONSE_THRESHOLD, ou outro balão (progresso de ferramenta, streaming) consumiu o token de resposta antes. Veja o bloco de silenciamento em "Respostas lentas do LLM".

"already in use by another profile". O mesmo token de acesso ao canal está vinculado a outro perfil do Hermes em execução. Pare o outro gateway ou use um canal separado.

Limitações​

  • Limites de balão e de tamanho. Cada balão de texto do LINE tem teto de 5000 caracteres. Respostas mais longas são fatiadas de forma inteligente em torno de 4500 caracteres, em até 5 balões por chamada de Reply/Push, quebrando em fronteiras naturais sempre que dá.
  • Sem edição nativa de mensagem. O LINE não tem API de editar mensagem — respostas em streaming sempre mandam balões novos, nunca editam os anteriores.
  • Sem renderização de Markdown. Negrito (**), itálico (*), blocos de código e títulos aparecem como caracteres literais. O adaptador remove tudo isso antes de enviar; as URLs são preservadas ([rótulo](url) vira rótulo (url)).
  • Indicador de carregamento só em DM. O LINE recusa a API de chat/loading em grupos e salas, então o indicador de digitação só aparece em conversas 1:1.