Lampson como motor

Canais

Um canal conecta um agente a uma plataforma de mensagens: o agente responde as mensagens dos seus clientes. O Lampson vem com dois e cada canal é um plugin, então você pode adicionar os que precisar:

Telegram — um bot, grátis e sem intermediários.
Chatwoot — uma caixa de atendimento que já junta WhatsApp, Instagram, Facebook, email e o chat do site: um único canal cobre tudo isso.

Para todos, o Lampson entra com o mesmo: uma conversa por cliente, a caixa de entrada que junta as mensagens em rajada em uma resposta, o «digitando…» enquanto o agente trabalha, as fotos como imagem para os modelos com visão, as permissões e o trace.

Comandos§

lampson channel list               # cada canal: ligado, agente, modo, URL do webhook
lampson channel on telegram        # ligar (decisão sua, como um plugin)
lampson channel setup telegram     # deixá-lo funcionando
lampson channel off telegram

Na web: Canais no painel esquerdo — ligar, ver o modo e o agente, «configurar» e os últimos eventos.

Qual agente responde: LAMPSON_CHANNEL_<CANAL>_AGENT=tienda em ~/lampson/.env (por exemplo LAMPSON_CHANNEL_TELEGRAM_AGENT). Se você não definir, o agente padrão. → Agentes

Com ou sem URL pública§

Uma plataforma avisa das mensagens novas chamando uma URL (um webhook). Se o seu Lampson tem URL pública (lampson --domain ou um túnel), lampson channel setup registra esse webhook.

Sem URL pública — o Lampson no computador da sua casa — os canais que permitem (Telegram) funcionam do mesmo jeito: lampson channel setup os passa para o modo sem URL pública e é o Lampson quem pede as mensagens novas à plataforma. Não precisa de domínio nem de túnel; só que o workspace esteja ligado (com o hub rodando, um workspace com canais fica ligado).

Telegram§

1. No Telegram, fale com o @BotFather, /newbot, e copie o token. 2. Em ~/lampson/.env: ``sh LAMPSON_TELEGRAM_TOKEN=123456789:AA… LAMPSON_TELEGRAM_WEBHOOK_SECRET=uma-frase-longa-qualquer LAMPSON_CHANNEL_TELEGRAM_AGENT=tienda ` 3. Na pasta do projeto: `sh lampson channel on telegram lampson channel setup telegram ``

Com URL pública, setup registra o webhook com o segredo (o Telegram o envia em cada aviso e o Lampson rejeita o que não o trouxer). Sem URL pública, passa para o modo sem URL pública.

O que o canal faz: responde as mensagens novas de pessoas (ignora edições, mensagens de outros bots e posts de canais); uma foto chega ao agente como imagem, com o texto dela; áudios, arquivos e localizações chegam como uma nota; as respostas longas são divididas em mensagens de até 4000 caracteres, cortando numa quebra de linha.

Se o token do bot ficou escrito em algum lugar compartilhado, gere outro no @BotFather (/revoke) e troque no .env.

Chatwoot§

Em teste. O canal segue a documentação oficial do Chatwoot e passa nos nossos testes contra um Chatwoot simulado, mas ainda não o testamos contra uma instância real. Se você usar e algo não funcionar, avise-nos.

1. No Chatwoot: Configurações → Integrações → Webhooks → URL https://seu-lampson/w/<workspace>/ch/chatwoot, evento message_created. Copie o segredo que ele mostra. 2. Um token de acesso (do seu perfil, ou de um agent bot) com permissão para responder. 3. Em ~/lampson/.env: ``sh LAMPSON_CHATWOOT_URL=https://app.chatwoot.com LAMPSON_CHATWOOT_TOKEN=… LAMPSON_CHATWOOT_WEBHOOK_SECRET=… LAMPSON_CHANNEL_CHATWOOT_AGENT=tienda ` 4. lampson channel on chatwoot`.

O canal verifica a assinatura do Chatwoot, responde só as mensagens recebidas e públicas (as próprias respostas e as notas privadas são ignoradas: senão, o bot responderia a si mesmo) e passa as imagens anexadas como imagem. O Chatwoot precisa de uma URL pública para chegar ao Lampson.

Escrever o seu próprio canal§

Um canal é um plugin com "channel" no seu plugin.json. Ele pode não ter ferramentas para o modelo:

{
  "name": "mi-canal",
  "description": "Minha plataforma de mensagens",
  "kind": "exec",
  "command": "node canal.js",
  "config": ["MICANAL_TOKEN"],
  "channel": {"agent": "", "typing": true, "poll": false}
}

"config" passa ao plugin os segredos dele a partir do .env: LAMPSON_MICANAL_TOKEN chega como PLUGIN_MICANAL_TOKEN. O plugin recebe a ação em PLUGIN_TOOL e os dados (JSON) em PLUGIN_ARGS, e imprime um JSON no stdout:

ação	recebe	imprime
`receive`	o webhook cru: `{method, path, query, headers, body}` (o body exato, para verificar assinaturas)	`{"messages": [{"thread", "text", "sent_at"?, "from"?, "images"?, "meta"?}], "http"?: {"status", "body"}}`
`send`	`{thread, text, meta, agent, session, batch}`	o que quiser; uma saída que começa com `ERROR` conta como falha
`typing` (opcional)	`{thread, meta}`	—
`setup` (opcional)	`{"mode": "webhook", "webhook_url"}` ou `{"mode": "poll"}`	uma mensagem para a pessoa
`poll` (opcional)	`{cursor}`	`{"messages": [...], "cursor": <o próximo>}`

O webhook de um canal é https://seu-lampson/w/<workspace>/ch/<canal>: o Lampson responde à plataforma na hora e o agente trabalha à parte. O que send recebe em meta é o que receive devolveu para a última mensagem do lote (os ids da sua plataforma). Cada canal tem um log em .lampson/channels/<canal>.log.

Você também pode pedir ao agente: «faça um canal para o Discord» — ele escreve com este contrato, valida e pede que você o ligue.

Ver como Markdown