> For the complete documentation index, see [llms.txt](https://ajuda.digitalsac.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ajuda.digitalsac.io/digicrm/operacao-uso-do-sistema/configuracoes/inteligencia-artificial.md).

# Inteligência Artificial

### Finalidade

A tela **Inteligência Artificial** cadastra **prompts/assistentes** que respondem automaticamente o **cliente no canal**, enquanto o ticket está `pending`/`bot`, **sem** atendente (`userId`) e **sem** fila (`queueId`). A ligação principal é o canal (`promptId`). As **filas** do prompt definem para onde a IA pode transferir.

Não confundir com:

| Recurso                                 | Papel                                                |
| --------------------------------------- | ---------------------------------------------------- |
| **Inteligência Artificial** (este guia) | Auto-resposta do canal via LLM                       |
| **Copilot IA**                          | Assistente do atendente no ticket                    |
| **Robô de Atendimento**                 | Fluxo visual (menus) no canal                        |
| Chaves em Gerais → Integrações          | Uso genérico (ex.: transcrição), não é este cadastro |

No canal, o destino é **exclusivo**: IA **ou** ChatBot **ou** Fila.

\[\[FOTO]]

***

### Caminho / permissão / licença

| Item                     | Valor                                                                  |
| ------------------------ | ---------------------------------------------------------------------- |
| **Menu**                 | Configurações → **Inteligência Artificial**                            |
| **URL**                  | `/configuracoes/prompt`                                                |
| **Módulo**               | Precisa do módulo **`activeia`** efetivo no tenant (senão o item some) |
| **Card no hub**          | `requireLicense: FREE` + gate do módulo                                |
| **Guard da rota**        | Também exige hierarquia **PREMIUM** no router                          |
| **Ausência de resposta** | Recurso **Cloud** (planos Cloud)                                       |

Documente os dois gates: módulo `activeia` **e** PREMIUM na rota.

\[\[FOTO]]

***

### Listagem

Modos tabela / cards. Busca por nome. Ações: Adicionar, Editar, Excluir.

| Coluna           | Conteúdo                        |
| ---------------- | ------------------------------- |
| Nome             | Nome do prompt                  |
| Provedor         | OpenAI, Anthropic, Gemini, etc. |
| ApiKey           | Mascarada                       |
| Tokens máximo    | Limite de geração               |
| Histórico máximo | Mensagens de contexto           |
| Temperatura      | Criatividade                    |
| Fila             | Filas vinculadas                |
| Ausência         | Resumo (quando Cloud)           |

\[\[FOTO]]

***

### Modal — abas e campos

Abas: **Geral** · **Prompt** · **Voz** · **Ausência**.

#### Aba Geral

| Campo                  | Obrigatório  | Para que serve                                                                                                                     |
| ---------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Nome**               | Sim          | Identificação                                                                                                                      |
| **ApiKey**             | Sim          | Chave do provedor (OpenAI / DigitalSac AI etc.)                                                                                    |
| **Modo de IA**         | —            | `chat` (Prompt), `assistant` (OpenAI Assistant), `agent` (Responses / prompt id). Modos assistant/agent só com chave OpenAI `sk-…` |
| **Assistant ID**       | Se assistant | ID `asst_…`                                                                                                                        |
| **Provedor do Agente** | Se agent     | Hoje tipicamente OpenAI                                                                                                            |
| **Agent Prompt ID**    | Se agent     | ID `pmpt_…`                                                                                                                        |
| **Provedor**           | Modo chat    | Auto, OpenAI, Anthropic, Gemini, Grok, DeepSeek, DigitalSac AI                                                                     |
| **Modelo**             | Modo chat    | Catálogo por provedor (oculto em assistant/agent)                                                                                  |
| **Filas**              | —            | Multi-select: filas para as quais a IA pode transferir                                                                             |
| **Tokens máximo**      | Modo chat    | Limite                                                                                                                             |
| **Histórico máximo**   | Modo chat    | Contexto                                                                                                                           |
| **Temperatura**        | Modo chat    | Criatividade                                                                                                                       |
| **Funções dinâmicas**  | —            | Indisponível / desabilitado na UI atual                                                                                            |

Hints na tela: em assistant/agent, modelo e instruções ficam no painel OpenAI; filas = transferências permitidas.

\[\[FOTO]]

#### Aba Prompt

| Campo               | Obrigatório        | Para que serve                                                               |
| ------------------- | ------------------ | ---------------------------------------------------------------------------- |
| **Texto do prompt** | Sim no modo `chat` | Instruções locais. Oculto no modo Assistant/Agent (instruções no Assistente) |

\[\[FOTO]]

#### Aba Voz

| Campo                 | Para que serve                |
| --------------------- | ----------------------------- |
| **Provedor / região** | Digitalsac Speech ou Azure    |
| **Chave API de voz**  | Credencial TTS                |
| **Resposta**          | Texto ou voz específica       |
| **Modelo TTS**        | XTTS v2 / F5-TTS (Digitalsac) |

\[\[FOTO]]

#### Aba Ausência (Cloud)

| Campo                          | Para que serve                           |
| ------------------------------ | ---------------------------------------- |
| **Habilitar ausência**         | Liga monitoramento de inatividade        |
| **Tempo de inatividade (min)** | Deve ser > 0                             |
| **Ação final**                 | Transferir para **fila** ou **encerrar** |
| **Fila de destino**            | Se ação = fila                           |
| **Mensagem ao encerrar**       | Opcional se ação = close                 |
| **Aviso antes**                | Mensagem + minutos de antecedência       |

Job periódico (\~60s) aplica aviso e depois a ação final.

\[\[FOTO]]

***

### Vincular ao canal

1. Configurações → **Cadastro de Canais**.
2. Tipo de atendimento: **Inteligência Artificial** (IA).
3. Selecione o prompt cadastrado.
4. Salvar — limpa ChatBot e Fila do mesmo canal.

#### Quando a IA responde

Mensagem do cliente, tipicamente se:

* Canal com `promptId`
* Mensagem não é do sistema (`!fromMe`)
* Ticket sem `userId` e sem `queueId`
* Status `pending` ou `bot`
* Não é grupo/broadcast (conforme canal)

A IA responde como bot; pode transferir para filas do prompt; áudio pode ser transcrito conforme configuração.

Quando um atendente assume (`userId`) ou o ticket ganha fila, o Prompt **para**.

\[\[FOTO]]

***

### Relação com Copilot e Robô

| Situação                  | Efeito                                     |
| ------------------------- | ------------------------------------------ |
| Canal com Prompt IA       | Copilot **não** auto-processa o ticket     |
| Canal com Robô (ChatFlow) | Fluxo visual; Prompt não é o destino       |
| Canal só com Fila         | Sem auto-resposta de IA/robô neste vínculo |

\[\[FOTO]]

***

### Erros comuns

| Sintoma                      | Causa provável                                                              |
| ---------------------------- | --------------------------------------------------------------------------- |
| Item some do menu            | Módulo `activeia` ausente                                                   |
| Rota bloqueada               | Guard PREMIUM                                                               |
| Ausência bloqueada           | Plano não Cloud                                                             |
| Assistant/Agent indisponível | Chave não é OpenAI `sk-`                                                    |
| Agent não salva              | Falta provider + `pmpt_…`                                                   |
| Resposta DeepSeek “errada”   | Chave `sk-` ambígua — force o provedor                                      |
| Funções dinâmicas            | Desligadas no front                                                         |
| Não responde                 | Canal sem `promptId`; ticket já com usuário/fila; exclusividade com ChatBot |

\[\[FOTO]]

***

### Fluxo operacional recomendado

1. Crie o prompt (apiKey, modo, filas, voz).
2. Associe ao canal.
3. Envie mensagem de teste no canal.
4. Confirme transferência para fila (se configurada).
5. Se Cloud, teste ausência com tempo curto em homologação.
6. Não misture Prompt + Robô + Fila no mesmo canal.

\[\[FOTO]]

***

### Dicas

* Um canal = um destino (IA **ou** robô **ou** fila).
* Use filas no prompt só para handoff controlado.
* Modo assistant/agent: gerencie instruções na OpenAI.
* Voz: configure chave e teste áudio real.
* Não confunda com **Copilot IA** (atendente) nem com chaves genéricas de Integrações.
* Após o humano assumir, a IA do canal deixa de responder naquele ticket.