--- title: Canais (Telegram, Chatwoot…) description: Conecte um agente do Lampson ao Telegram, ao WhatsApp e Instagram via Chatwoot, ou a qualquer plataforma com um plugin de canal — até sem URL pública. --- # 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](/pt/docs/plugins), 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](/pt/docs/api#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](/pt/docs/agents#ferramentas-e-permissoes) e o trace. ## Comandos ```sh 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__AGENT=tienda` em `~/lampson/.env` (por exemplo `LAMPSON_CHANNEL_TELEGRAM_AGENT`). Se você não definir, o agente padrão. → [Agentes](/pt/docs/agents) ## 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`](/pt/docs/phone) 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](https://github.com/kitecosmic/lampson/issues). 1. No Chatwoot: **Configurações → Integrações → Webhooks** → URL `https://seu-lampson/w//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: ```json { "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 webhook de um canal é `https://seu-lampson/w//ch/`: 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/.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.