Modulo 5.6 - Integracao com Canais

🌐 Web Chat: Widget Embeddable

O canal mais customizavel que existe. Um widget de chat no seu site ou SaaS da ao usuario acesso instantaneo ao assistente sem sair da pagina. Voce controla design, UX, dados coletados e integracao com seu backend.

🎯 Conceito Principal

Existem duas abordagens para embeddar chat no site: iframe (simples, isolado, sem conflitos de CSS) e JavaScript SDK (flexivel, acessa DOM do host, estilo nativo). A maioria dos SaaS usa SDK porque permite integracao profunda com o produto.

A comunicacao em tempo real usa WebSocket (bidirecional, baixa latencia, ideal para chat) ou SSE (Server-Sent Events) (unidirecional servidor-para-cliente, mais simples, bom para streaming de respostas). WebSocket e o padrao para chat. SSE funciona bem quando voce so precisa enviar a resposta em chunks.

• Iframe: Zero conflito CSS, sandbox de seguranca, facil de integrar. Limitacao: nao acessa contexto da pagina host
• JS SDK: Controle total, pode ler URL/contexto da pagina, estilo customizavel. Risco: conflitos de CSS com a pagina host
• Shadow DOM: O melhor dos dois mundos. SDK com encapsulamento de estilo. Usado por Intercom, Crisp, Drift

💻 Widget Minimo com WebSocket

// Embed script - cola no <body> do site

const chatWidget = document.createElement('div')

chatWidget.id = 'my-bot-widget'

document.body.appendChild(chatWidget)

// Conexao WebSocket com o backend

const ws = new WebSocket('wss://api.meubot.com/chat')

ws.onmessage = (event) => {

const data = JSON.parse(event.data)

renderMessage(data.text, 'bot')

}

function sendMessage(text) {

ws.send(JSON.stringify({ text, page: window.location.href }))

renderMessage(text, 'user')

}

</script>

🎨 Customizacao de Brand

CSS Variables

--chat-primary: #0F766E;

--chat-bg: #ffffff;

--chat-font: 'Inter', sans-serif;

--chat-radius: 12px;

--chat-position: bottom-right;

Exponha variaveis CSS para que o cliente personalize cores, fontes e posicao sem mexer no codigo.

Config Object

MeuBot.init({

apiKey: 'pk_...',

theme: 'light',

position: 'bottom-right',

greeting: 'Oi! Como ajudo?'

})

Objeto de configuracao para inicializacao. Inclua API key, tema, mensagem de boas-vindas e posicao.

💡 Dica Pratica

Use Shadow DOM para evitar conflitos de CSS. Quando voce injeta um widget numa pagina desconhecida, os estilos dela podem quebrar o seu chat e vice-versa. Shadow DOM cria um escopo isolado. E assim que Intercom, Crisp e todo widget de chat profissional funciona.

🤖 Telegram Bot API

A melhor plataforma para bots pessoais e MVPs. API gratuita, sem limites de mensagens, suporte a arquivos, audio, inline keyboards e webhooks. Se voce esta comecando, comece aqui.

🎯 Conceito Principal

Tudo comeca no @BotFather. Voce cria o bot, recebe um token, e a partir dai tem acesso a toda a Telegram Bot API. Duas formas de receber mensagens: polling (seu servidor pergunta ao Telegram periodicamente) ou webhook (Telegram envia para seu endpoint quando chega mensagem).

Polling e mais simples (sem SSL, sem dominio). Webhook e mais eficiente (sem delay, sem requests desnecessarios). Para producao, use webhook. Para desenvolvimento, polling resolve.

🔧 Setup Completo do Bot

Criar no BotFather

Abra @BotFather no Telegram, /newbot, defina nome e username. Guarde o token.

Configurar Webhook

POST https://api.telegram.org/bot{TOKEN}/setWebhook

{ "url": "https://meubot.com/webhook" }

Receber e Responder

// Handler do webhook

app.post('/webhook', async (req, res) => {

const { message } = req.body

const chatId = message.chat.id

const text = message.text

const response = await processMessage(text)

await bot.sendMessage(chatId, response)

res.sendStatus(200)

})

Tipos de Mensagem

• Texto: message.text - o mais comum
• Voz: message.voice - file_id para download + transcricao
• Foto: message.photo - array de tamanhos, pegue o ultimo
• Documento: message.document - qualquer arquivo ate 50MB
• Callback: callback_query - clique em inline keyboard

Inline Keyboards

bot.sendMessage(chatId, 'Escolha:', {

reply_markup: {

inline_keyboard: [[

{ text: 'Suporte', callback_data: 'support' },

{ text: 'Vendas', callback_data: 'sales' }

]]

}

})

Botoes interativos que enviam callback_query quando clicados. Use para menus, confirmacoes e navegacao.

👥 Group Chat Support

• Privacy mode (padrao): Bot so recebe mensagens que comecam com / ou mencionam o bot. Bom para grupos.
• Sem privacy mode: Bot recebe TODAS as mensagens do grupo. Necessario para bots de moderacao ou contexto completo.
• Dica: Filtre por chat.type ('private' vs 'group' vs 'supergroup') para comportamento diferente por contexto.

💡 Dica Pratica

Sempre filtre por ALLOWED_CHAT_ID em bots pessoais. Sem isso, qualquer pessoa que encontrar seu bot pode usa-lo (e gastar seus tokens de API). Um simples if (chatId !== ALLOWED_CHAT_ID) return; no inicio do handler resolve. Para bots publicos, implemente rate limiting por usuario.

💬 WhatsApp Business API

O canal onde seus clientes ja estao. 2 bilhoes de usuarios ativos. Mas a API oficial tem regras rigidas: janela de 24h, templates pre-aprovados, verificacao Meta Business. Vale o trabalho quando o publico e comercial.

🎯 Conceito Principal

O WhatsApp Cloud API (hospedado pela Meta) e a forma oficial de integrar. Voce registra no Meta Business, cria um app no developers.facebook.com, configura o webhook e comeca a receber mensagens. A alternativa on-premise (hospedada por voce) foi descontinuada em favor do Cloud API.

A regra mais importante: a janela de 24 horas. Quando o usuario manda mensagem, voce tem 24h para responder livremente. Depois disso, so pode enviar message templates pre-aprovados pela Meta. Isso inclui notificacoes, lembretes e follow-ups.

⚙️ Setup do WhatsApp Cloud API

Meta Business Verification

Crie conta no business.facebook.com, verifique o negocio (documentos, dominio). Pode levar 1-5 dias uteis.

Criar App e Configurar API

developers.facebook.com > Create App > Business > WhatsApp. Gere o access token permanente.

Registrar Webhook

Configure o endpoint que recebe mensagens. Webhook verification com token de verificacao + challenge.

Aprovar Message Templates

Crie templates para mensagens fora da janela de 24h. Categorias: marketing, utility, authentication. Aprovacao em ate 24h.

💻 Enviar Mensagem via Cloud API

// Enviar texto dentro da janela de 24h

const response = await fetch(

`https://graph.facebook.com/v19.0/${PHONE_ID}/messages`,

{

method: 'POST',

headers: {

'Authorization': `Bearer ${ACCESS_TOKEN}`,

'Content-Type': 'application/json'

body: JSON.stringify({

messaging_product: 'whatsapp',

to: '5511999999999',

type: 'text',

text: { body: 'Oi! Como posso ajudar?' }

})

}

)

🚨 Regra das 24 Horas

Quando o usuario manda mensagem, voce tem 24h para responder livremente. Depois:

✗ Nao pode enviar mensagens de texto livre
✗ Nao pode enviar midia sem template
✓ Pode enviar message templates pre-aprovados (pagos)
✓ Templates de utilidade sao mais baratos que marketing

📎 Tipos de Media Suportados

🖼️

Imagem

JPEG, PNG ate 5MB

🎥

Video

MP4 ate 16MB

📄

Documento

PDF, DOC ate 100MB

🎵

Audio

OGG, MP3 ate 16MB

💡 Dica Pratica

Teste com o numero de teste do Meta antes de usar numero real. O Cloud API fornece um numero de sandbox para desenvolvimento. Nao gaste dinheiro com templates ate validar o fluxo completo. E sempre salve o timestamp da ultima mensagem do usuario para controlar a janela de 24h no seu backend.

🔄 Adapter Pattern: Uma API, Multiplos Canais

Sem adapter pattern, cada canal novo significa reescrever a logica do bot. Com adapter, voce escreve a logica uma vez e conecta em qualquer canal. E o padrao que separa projetos amadores de plataformas reais.

🎯 Conceito Principal

O Adapter Pattern cria uma camada de normalizacao entre canais e logica de negocio. Cada canal tem um inbound adapter (normaliza a mensagem recebida para formato interno) e um outbound adapter (formata a resposta para o canal de saida).

O formato interno (normalized message) e o contrato entre adapters e logica. Contem: from (quem mandou), text (conteudo), channel (de onde veio), metadata (extras do canal original). O router e os bots especialistas nunca sabem de qual canal a mensagem veio.

🔄 Fluxo do Adapter Pattern

📱

Canal

Telegram, WhatsApp, Web

📥

Inbound

Normaliza mensagem

🧠

Router + Bot

Processa logica

📤

Outbound

Formata resposta

💬

Resposta

Volta pro canal

💻 Interface do Adapter

// Formato normalizado interno

interface NormalizedMessage {

id: string

from: { id: string, name?: string }

text: string

channel: 'telegram' | 'whatsapp' | 'webchat'

timestamp: number

attachments?: Attachment[]

metadata: Record<string, any>

}

// Cada canal implementa este contrato

interface ChannelAdapter {

normalize(raw: any): NormalizedMessage

send(to: string, response: BotResponse): Promise<void>

}

// Adapter Telegram

class TelegramAdapter implements ChannelAdapter {

normalize(update) {

return {

id: update.message.message_id,

from: { id: update.message.chat.id },

text: update.message.text,

channel: 'telegram',

timestamp: update.message.date,

metadata: { chatType: update.message.chat.type }

}

✓ Boas Praticas

✓ Manter a logica de negocio 100% agnostica ao canal
✓ Normalizar attachments para formato unico
✓ Testes unitarios por adapter isoladamente
✓ Registrar canal de origem no log para debug

✗ Erros Comuns

✗ if/else para cada canal dentro da logica do bot
✗ Hardcodar formatacao Telegram no core
✗ Enviar markdown sem checar suporte do canal
✗ Ignorar limites de tamanho por canal

💡 Dica Pratica

Comece com 2 adapters: Telegram + Web Chat. Isso forca voce a criar a camada de normalizacao desde o inicio. Se funciona com 2, funciona com 10. Adicionar WhatsApp, Slack ou Discord depois e so criar um novo adapter que implementa a mesma interface.

🧩 LangBot e Botpress

Nao precisa reinventar a roda. Frameworks multichannel ja resolveram os problemas de adapter, NLU e deployment. A questao e: quando usar framework vs quando construir custom.

🎯 Conceito Principal

LangBot e open-source, suporta 10+ plataformas (Telegram, WhatsApp, Discord, Slack, WeChat, Line, etc.) com uma API unificada. Self-hosted, integra com qualquer LLM. Ideal para quem quer controle total e nao quer ficar preso a vendor.

Botpress e um visual builder com 10 canais nativos. NLU integrado, analytics, versioning, collaboration. Free tier generoso. Bom para times com membros nao-tecnicos que precisam editar fluxos sem tocar codigo.

📊 Comparativo Detalhado

Criterio	LangBot	Botpress	Custom
Canais	10+	10	Quanto voce implementar
Hosting	Self-hosted	Cloud + self-hosted	Seu servidor
LLM Integration	Qualquer (API)	OpenAI + custom	Total controle
Visual Builder	Nao	Sim (principal feature)	Nao
Custo	Gratis (OSS)	Free tier + planos pagos	Tempo de dev
Curva de Aprendizado	Media	Baixa	Alta

Use LangBot quando

• Quer open-source e self-hosted
• Precisa de canais exoticos (WeChat, Line)
• Time tecnico que prefere codigo
• Privacidade e controle total dos dados

Use Botpress quando

• Time misto (tecnico + nao-tecnico)
• Precisa de visual builder para fluxos
• Quer analytics e NLU prontos
• Prefere nao gerenciar infra

Build Custom quando

• Requisitos que nenhum framework atende
• Precisa de performance extrema
• Bot e o core do produto (nao ferramenta auxiliar)
• Quer zero dependencia externa

💡 Dica Pratica

Prototipe com Botpress, produza com custom ou LangBot. Botpress e rapido para validar fluxos e canais. Mas quando voce precisa de logica sofisticada (router multibot, memoria personalizada, modelos mixtos), frameworks genericos limitam. O ideal e usar framework pra validar e migrar pro custom quando o produto amadurece.

🏗️ Exercicio: Conectar 2 Canais

Hora de colocar a teoria em pratica. Voce vai deployar o mesmo bot em 2 canais: web chat + Telegram. Mesma logica, mesmos especialistas, adapters diferentes. Quando funcionar nos dois, voce tem uma plataforma multichannel real.

🏗️

Exercicio: Bot Multichannel

Tempo estimado: 25-35 minutos

Crie o formato normalizado

Defina a interface NormalizedMessage que sera o contrato entre adapters e logica:

{ id, from, text, channel, timestamp, metadata }

Implemente TelegramAdapter

normalize() converte Update do Telegram para NormalizedMessage. send() usa bot.sendMessage():

class TelegramAdapter {

normalize(update) { ... }

async send(chatId, response) { await bot.sendMessage(chatId, response.text) }

}

Implemente WebChatAdapter

normalize() converte payload WebSocket para NormalizedMessage. send() emite pelo socket:

class WebChatAdapter {

normalize(payload) { ... }

async send(socketId, response) { io.to(socketId).emit('message', response) }

}

Conecte ambos ao mesmo router

O router recebe NormalizedMessage e nao sabe de qual canal veio:

const msg = adapter.normalize(raw)

const response = await router.process(msg)

await adapter.send(msg.from.id, response)

Teste em ambos os canais

Envie a mesma pergunta no Telegram e no web chat. A resposta deve ser identica:

Telegram: "qual o preco do plano pro?" → Bot Vendas responde

Web Chat: "qual o preco do plano pro?" → Bot Vendas responde (identico)

✅ Criterios de Sucesso

☐ NormalizedMessage interface definida

☐ TelegramAdapter normalize + send funcionando

☐ WebChatAdapter normalize + send funcionando

☐ Mesma resposta em ambos os canais

🌟 Bonus

Adicione um terceiro canal: Discord. Se sua arquitetura de adapters esta certa, voce so precisa criar DiscordAdapter com normalize() e send(). A logica, o router e os especialistas nao mudam nada. Esse e o poder do adapter pattern.

📋 Resumo do Modulo

✓

Web chat com Shadow DOM e WebSocket para tempo real - Widget embeddable com isolamento de estilo e comunicacao bidirecional.

✓

Telegram: BotFather, webhook, inline keyboards, file handling - A melhor plataforma para bots pessoais e MVPs. Gratuita, sem limites.

✓

WhatsApp Cloud API com janela de 24h e message templates - Para atendimento comercial. Requer verificacao Meta Business.

✓

Adapter Pattern: escreva logica uma vez, conecte em qualquer canal - NormalizedMessage como contrato entre adapters e router.

✓

LangBot (open-source, 10+ canais) e Botpress (visual builder) - Frameworks para quem nao quer reinventar adapters.

✓

Bot funcionando em Telegram + Web Chat com mesma logica - Exercicio pratico validando a arquitetura multichannel.

Proximo Modulo:

Modulo 5.7 - Implementar Multibot (Exercicio Final): construa o sistema completo com router + especialistas + canais + fallback.

← Modulo Anterior Voltar para Trilha 5 Modulo 5.7: Exercicio Final →