# MANUAL TÉCNICO - CANAIS DE ENTRADA (EMAIL/CHAT/TELEGRAM) - ZAMMAD

**Código:** ITGINF 0005/26 | **Classificação:** INTERNO
**Responsável:** João Pedro Toledo Gonçalves | **Data:** {{DATA_ATUAL}}

## 1. HISTÓRICO DE REVISÃO

| Data | Versão | Descrição | Autor |
| :--- | :--- | :--- | :--- |
| {{DATA_ATUAL}} | 1.0 | Criação Inicial | João Pedro Toledo Gonçalves |

## 2. OBJETIVO
Centralizar canais de comunicação. Configurar Email (M365/Google), Telegram Bot e Widget de Chat no site.

## 3. PRÉ-REQUISITOS
*   [ ] Conta Microsoft 365 ou Google Admin (para Email).
*   [ ] Conta Telegram (para Bot).
*   [ ] Acesso ao HTML do site da empresa (para Chat).

## 4. PASSO A PASSO (EXECUÇÃO)

### Etapa 1: Email (Microsoft 365)
Zammad recomenda OAuth2 (mais seguro que IMAP/SMTP puro).

1.  Acesse **Admin** > **Canais** > **Microsoft 365**.
2.  Clique em **Adicionar Conta**.
3.  Faça login com a conta de email do suporte (ex: `suporte@empresa.com`).
4.  Aceite as permissões do App Enterprise.
5.  No Zammad, defina:
    *   **Grupo de Destino:** `Service Desk`.
    *   **Pasta:** `Inbox`.
    *   **Manter mensagens no servidor:** `Não` (O Zammad deve deletar após importar para não encher a caixa).

### Etapa 2: Telegram Bot
Permita que clientes abram chamados enviando msg no Telegram.

1.  No seu Telegram, chame o **@BotFather**.
2.  Envie `/newbot`.
3.  Escolha o nome e user (ex: `EmpresaSuporteBot`).
4.  Copie o **API Token** gerado (ex: `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`).
5.  No Zammad: **Admin** > **Canais** > **Telegram**.
6.  Cole o Token e configure o Grupo de Entrada.
7.  Envie uma mensagem de "Oi" para o Bot e veja o ticket aparecer.

![Integration Telegram](assets/zammad_telegram_integr.png)

### Etapa 3: Widget de Chat
Botão flutuante para seu site.

1.  Acesse **Admin** > **Canais** > **Chat**.
2.  Ative o canal.
3.  Copie o código JavaScript fornecido no final da página.
4.  Cole no `<body>` do seu site institucional ou WordPress.
5.  **Funcionamento:** O chat só aparece "Online" se um agente estiver com a aba do Zammad aberta e o botão "Chat" (no topo) ativado.

## 5. SOLUÇÃO DE PROBLEMAS (TROUBLESHOOTING)

!!! warning "Pânico: Canal Parou"
    Clientes reclamam que mandam email e nada acontece.

**Problema 1: Email fetching parou (Token Expirado)**
*   **Causa:** O Token OAuth2 do Microsoft 365 expirou ou a senha mudou.
*   **Solução:**
    1.  Vá em **Canais** > **Microsoft 365**.
    2.  Se houver erro vermelho, clique em **Re-autenticar**.

**Problema 2: Telegram não cria tickets**
*   **Causa:** Webhook falhou. O Zammad precisa ser HTTPS público.
*   **Solução:**
    1.  Se o Zammad for interno (LAN), o Telegram não consegue entregar a mensagem.
    2.  Use um Proxy Reverso com SSL válido (LetsEncrypt).

**Problema 3: Email Microsoft bloqueado (Auth Error)**
*   **Causa:** "Authenticated SMTP" desativado no Tenant.
*   **Solução:**
    1.  Admin do M365 deve ir no usuário > **Mail** > **Manage email apps**.
    2.  Marcar **Authenticated SMTP**.

## 6. DADOS TÉCNICOS

| Canal | Protocolo | Notas |
| :--- | :--- | :--- |
| **Email** | IMAPS/SMTP (OAuth) | Limite de anexo 10MB (ajustável). |
| **Telegram** | HTTPS Webhook | Não suporta anexos > 20MB. |
| **Chat** | WebSocket | Requer porta 80/443 liberada. |

## 7. VALIDAÇÃO FINAL
- [ ] Envie um email externo e cronometre quanto tempo leva para virar ticket (Média: 1-2 min).
- [ ] Mande mensagem no Telegram e verifique a criação instantânea.
