> For the complete documentation index, see [llms.txt](https://traga-ja.gitbook.io/traga-ja/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://traga-ja.gitbook.io/traga-ja/whatsapp.md).

# WhatsApp

## Integração WhatsApp — Guia de Uso

### Visão Geral

A integração com WhatsApp permite enviar notificações automáticas para os clientes a cada mudança de status do pedido, além de configurar respostas automáticas para mensagens recebidas.

***

### Passo 1 — Ativar a Integração

Ao acessar a seção **WhatsApp** no dashboard pela primeira vez, o sistema estará desconfigurado.

1. Clique em **"Ativar WhatsApp"**
2. O sistema inicializa a integração e abre automaticamente o modal de conexão com QR Code

> Se o servidor não estiver rodando, um aviso amarelo será exibido informando que as configurações não estão disponíveis.

<figure><img src="https://3112138314-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F03FNhFX3GgByGAyQ7GlQ%2Fuploads%2FqTIXZTi2DZmumpJgxKNz%2Fimage.png?alt=media&amp;token=45f40009-e599-40ca-b2f4-96eb41ef1ef1" alt=""><figcaption></figcaption></figure>

***

### Passo 2 — Conectar via QR Code

Após ativar, o modal de QR Code será exibido automaticamente. Caso precise reconectar no futuro, clique em **"Conectar"** na barra de status.

**No celular:**

1. Abra o **WhatsApp**
2. Toque em **Mais opções** (três pontos) — Android — ou **Configurações** — iPhone
3. Toque em **Dispositivos conectados**
4. Toque em **Conectar um dispositivo**
5. Aponte a câmera para o QR Code exibido na tela

<figure><img src="https://3112138314-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F03FNhFX3GgByGAyQ7GlQ%2Fuploads%2FrhQCXyR7Uc6F8osQeDiN%2Fimage.jpg?alt=media&amp;token=8a2093b4-0df1-4a7d-8d9f-6870722445bc" alt=""><figcaption></figcaption></figure>

> O modal fecha automaticamente após a leitura bem-sucedida do QR Code. O número do telefone conectado aparecerá na barra de status.

**Observação:** O QR Code expira após alguns minutos. Se expirar, feche o modal e clique em **"Conectar"** novamente.

***

### Passo 3 — Configurar Notificações de Pedidos

Após conectar, a seção **"Configurações de Notificações"** ficará visível. Escolha quais eventos disparam mensagens automáticas para o cliente:

| Evento                             | Descrição                                                |
| ---------------------------------- | -------------------------------------------------------- |
| Pedido Recebido                    | Quando um novo pedido é criado                           |
| Pedido em Preparo                  | Quando o pedido começa a ser preparado                   |
| Pedido em Entrega                  | Quando o pedido sai para entrega                         |
| Pedido Finalizado                  | Quando o pedido é entregue                               |
| Pedido Recusado                    | Quando o pedido é recusado                               |
| Atualização de Fidelidade/Cashback | Enviada após finalização, com saldo de pontos e cashback |

Use os **toggles** para ativar ou desativar cada tipo. Clique em **"Salvar Configurações"** para aplicar.<br>

<figure><img src="https://3112138314-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F03FNhFX3GgByGAyQ7GlQ%2Fuploads%2FLlf7SP7SA3pEGHBoR2Rh%2Fimage.png?alt=media&amp;token=8225806d-1741-42d0-8f8b-05d19b5d6971" alt=""><figcaption></figcaption></figure>

***

### Passo 4 — Configurar Resposta Automática

A seção **"Resposta Automática"** permite responder automaticamente clientes que enviam mensagens pelo WhatsApp da empresa.

1. Ative o toggle **"Habilitar Resposta Automática"**
2. Defina o **intervalo entre respostas** (cooldown) para o mesmo cliente:
   * Use os atalhos: **1 hora**, **6 horas** ou **24 horas**
   * Ou digite manualmente (mínimo: 1 minuto, máximo: 1440 minutos)
3. Clique em **"Salvar Configurações"** (o botão aparece apenas quando houver alterações)

> O cooldown evita que o mesmo cliente receba múltiplas respostas automáticas em curto intervalo.

<figure><img src="https://3112138314-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F03FNhFX3GgByGAyQ7GlQ%2Fuploads%2F43mtc6oLmVP2bdBPoxzB%2FScreenshot%202026-04-07%20at%2023-30-39%20WhatsApp%20-%20Dashboard%20-%20Traga%20J%C3%A1.png?alt=media&amp;token=5915c2b7-90b5-4982-b122-6b288e35c988" alt=""><figcaption></figcaption></figure>

***

### Passo 5 — Personalizar Mensagens (Templates)

A seção **"Personalizar Mensagens"** permite editar o texto de cada mensagem enviada automaticamente.

#### Categorias de templates

**Respostas Automáticas:**

* `💬 Auto-Resposta (Aberto)` — Enviada quando o cliente fala com o número e a empresa está aberta
* `🕐 Auto-Resposta (Fechado)` — Enviada fora do horário de funcionamento

**Notificações de Pedidos:**

* `📦 Pedido Recebido`
* `⏳ Pedido em Preparo`
* `🛵 Pedido em Entrega`
* `✅ Pedido Finalizado`
* `❌ Pedido Recusado`
* `🎁 Atualização Fidelidade`

#### Variáveis disponíveis nos templates

Use as variáveis abaixo no texto — elas são substituídas automaticamente pelos dados reais no momento do envio:

| Variável                  | Descrição                                     |
| ------------------------- | --------------------------------------------- |
| `{customerName}`          | Nome do cliente                               |
| `{orderNumber}`           | Número do pedido                              |
| `{items}`                 | Lista de itens do pedido                      |
| `{subtotal}`              | Subtotal do pedido                            |
| `{deliveryFee}`           | Taxa de entrega                               |
| `{discountDetails}`       | Detalhes de desconto aplicado                 |
| `{total}`                 | Valor total do pedido                         |
| `{paymentMode}`           | Forma de pagamento                            |
| `{estimatedDeliveryTime}` | Tempo estimado de entrega                     |
| `{companyName}`           | Nome da empresa                               |
| `{companySlug}`           | Slug da empresa (para link do cardápio)       |
| `{completedOrdersCount}`  | Pedidos completados no programa de fidelidade |
| `{ordersToEarnReward}`    | Total de pedidos necessários para recompensa  |
| `{ordersRemaining}`       | Pedidos restantes para atingir a recompensa   |
| `{cashbackEarned}`        | Cashback ganho no pedido atual                |
| `{cashbackBalance}`       | Saldo total de cashback disponível            |

<figure><img src="https://3112138314-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F03FNhFX3GgByGAyQ7GlQ%2Fuploads%2FtSkpcYEa3ijQoQIVnaU2%2FWhatsApp%20Image%202026-04-07%20at%2023.34.52.jpeg?alt=media&amp;token=75be419b-1912-43d5-bee7-9ad7cb1c0235" alt=""><figcaption></figcaption></figure>

#### Como editar

1. Selecione a aba do template desejado
2. Edite o texto no editor
3. Para restaurar o texto original, clique em **"Restaurar padrão"** na aba ativa
4. Clique em **"Salvar Templates"** para aplicar todas as alterações

***

### Passo 6 — Testar o Envio

Com o WhatsApp conectado, use o botão **"Enviar Mensagem Teste"** na barra de status para validar a integração.

1. Clique em **"Enviar Mensagem Teste"**
2. Informe o número de destino com código do país e DDD:
   * Exemplo: `5511999999999`
3. Edite ou mantenha a mensagem padrão
4. Clique em **"Enviar"**

<figure><img src="https://3112138314-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F03FNhFX3GgByGAyQ7GlQ%2Fuploads%2FaC1GrFpPUCpkXpUJMj1j%2FSem%20t%C3%ADtulo.png?alt=media&amp;token=6b259093-647d-4e43-8a08-f343be4a346c" alt=""><figcaption></figcaption></figure>

> A mensagem é enviada imediatamente. Use um número real para confirmar o recebimento.

***

### Desconectar o WhatsApp

Para desconectar o número vinculado:

1. Clique em **"Desconectar"** na barra de status
2. Confirme a ação

Após desconectar, o status voltará para **"Desconectado"** e o botão **"Conectar"** ficará disponível para vincular novamente via QR Code.