81 lines
3.4 KiB
Markdown
81 lines
3.4 KiB
Markdown
# Automações ▸ Envio de e-mails (guia de manutenção)
|
|
|
|
## Visão geral
|
|
O envio de e-mails via automações funciona como uma **ação** dentro do motor de automações de tickets.
|
|
|
|
Por motivos de compatibilidade e segurança:
|
|
- O HTML do e-mail é gerado com **tabelas + CSS inline** (compatível com Gmail/Outlook/Apple Mail).
|
|
- O envio (SMTP) acontece em **Convex Action** (`"use node"`), porque mutações Convex não devem fazer I/O de rede.
|
|
|
|
## Onde as automações disparam
|
|
Os eventos de ticket chamam o motor de automações em `convex/tickets.ts`:
|
|
- Criação do ticket (`TICKET_CREATED`)
|
|
- Alteração de status (`STATUS_CHANGED`)
|
|
- Alteração de prioridade (`PRIORITY_CHANGED`)
|
|
- Alteração de fila (`QUEUE_CHANGED`)
|
|
- Inclusão de comentário (`COMMENT_ADDED`)
|
|
- Finalização/resolução (`TICKET_RESOLVED`)
|
|
|
|
## Onde a ação é validada e aplicada
|
|
Arquivo: `convex/automations.ts`
|
|
|
|
Pontos principais:
|
|
- **Validação/parse** da ação `SEND_EMAIL` em `parseAction(...)`.
|
|
- **Execução** em `applyActions(...)`:
|
|
- Resolve destinatários (solicitante, responsável, usuário interno e e-mails livres).
|
|
- Faz interpolação de variáveis `{{...}}` em assunto/mensagem.
|
|
- Gera o HTML via **React Email** em `convex/reactEmail.tsx` (usando `@react-email/render`).
|
|
- Agenda o envio via `ctx.scheduler.runAfter(1, api.ticketNotifications.sendAutomationEmail, ...)`.
|
|
|
|
## Onde o e-mail é enviado de fato (SMTP)
|
|
Arquivo: `convex/ticketNotifications.ts`
|
|
|
|
- A action `sendAutomationEmail` faz o envio via SMTP e aceita:
|
|
- `to`: lista de destinatários
|
|
- `subject`: assunto
|
|
- `html`: HTML já renderizado
|
|
|
|
Observação: para não “vazar” destinatários entre si, o envio é feito **um-a-um** (um e-mail por destinatário).
|
|
|
|
## Templates de e-mail
|
|
Templates (React Email) ficam em `emails/` e podem ser pré-visualizados localmente.
|
|
|
|
Templates adicionados:
|
|
- `emails/automation-email.tsx`: usado pela ação `SEND_EMAIL` (inclui cartão com dados do ticket + CTA).
|
|
- `emails/simple-notification-email.tsx`: usado por notificações simples (comentário público / encerramento).
|
|
|
|
Renderização para HTML (backend):
|
|
- `convex/reactEmail.tsx`: `renderAutomationEmailHtml(...)` e `renderSimpleNotificationEmailHtml(...)`.
|
|
|
|
## Variáveis suportadas (interpolação)
|
|
Você pode usar estas variáveis em **Assunto** e **Mensagem**:
|
|
- `{{ticket.reference}}`
|
|
- `{{ticket.subject}}`
|
|
- `{{ticket.status}}`
|
|
- `{{ticket.priority}}`
|
|
- `{{company.name}}`
|
|
- `{{requester.name}}`
|
|
- `{{assignee.name}}`
|
|
- `{{ticket.url.portal}}`
|
|
- `{{ticket.url.staff}}`
|
|
- `{{automation.name}}`
|
|
|
|
## Link do botão (CTA)
|
|
A UI permite escolher:
|
|
- `Auto` (padrão): se houver destinatário interno (responsável/usuário) usa **Painel**; caso contrário usa **Portal**.
|
|
- `Portal (cliente)`: `/portal/tickets/:id`
|
|
- `Painel (agente)`: `/tickets/:id`
|
|
|
|
Se você precisar enviar para cliente **e** agente no mesmo evento, prefira criar **duas ações SEND_EMAIL** (uma com link Portal e outra com link Painel).
|
|
|
|
## Variáveis de ambiente (SMTP)
|
|
O envio no Convex tenta usar:
|
|
- `SMTP_ADDRESS` ou `SMTP_HOST`
|
|
- `SMTP_USERNAME` ou `SMTP_USER`
|
|
- `SMTP_PASSWORD` ou `SMTP_PASS`
|
|
- `SMTP_PORT` (default `465`)
|
|
- `MAILER_SENDER_EMAIL` (legacy) ou `SMTP_FROM_EMAIL` + `SMTP_FROM_NAME`
|
|
|
|
## Testes de regressão
|
|
Arquivo: `tests/automations-engine.test.ts`
|
|
- Teste adiciona um cenário onde a ação `SEND_EMAIL` está presente e valida que o envio é agendado via `scheduler.runAfter`.
|