> ## Documentation Index
> Fetch the complete documentation index at: https://doc.omnitechsolucoes.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuração de Widgets

> Guia completo para configurar widgets de Estatística, Gráfico e Tabela com todas as opções disponíveis

Aprenda como configurar cada tipo de widget com explicações detalhadas de cada opção.

## Criando Widgets

1. Navegue até o dashboard personalizado
2. Clique em **"Manage Widgets"** e depois em **"Create New Widget"**
3. Selecione o tipo de widget
4. Siga o assistente de 2 a 3 etapas
5. Salve e adicione ao dashboard

## Widgets de Estatística (Stat)

Exibição de uma única métrica com comparação opcional e gráfico de tendência.

### Etapa 1: Básico

**Nome do Widget**

* Identificador interno para a lista de widgets
* Não é exibido no dashboard
* Exemplo: "Total Calls This Month"

**Tabela de Dados**

* Escolha a fonte de dados: calls, leads, campaigns, assistants, phone\_numbers, sms
* Determina as colunas disponíveis

**Agregação**

* `COUNT` - Número total de registros (nenhuma coluna necessária)
* `SUM` - Soma dos valores (requer seleção de coluna)
* `AVG` - Média dos valores (requer seleção de coluna)
* `MAX` - Valor máximo (requer seleção de coluna)
* `MIN` - Valor mínimo (requer seleção de coluna)

**Coluna** (se SUM/AVG/MAX/MIN selecionado)

* Selecione a coluna numérica para agregar
* Exemplo: `duration` para duração média da chamada
* Não é necessário para COUNT

### Etapa 2: Exibição e Filtros

**Label** (obrigatório)

* Título principal exibido no widget
* Exemplo: "Total Calls"

**Description**

* Texto opcional abaixo do valor
* Oculto se a comparação estiver ativada
* Exemplo: "Calls made this month"

**Color**

* primary (azul), success (verde), warning (amarelo), danger (vermelho), info (ciano), gray
* Escolha com base no tipo de métrica (verde para positivo, vermelho para negativo)

**Show Mini Chart**

* Exibe um pequeno gráfico de linha mostrando a tendência diária
* Usa o mesmo intervalo de datas da estatística

**Compare with Previous Period**

* Mostra a variação percentual em relação ao período anterior
* Exemplo: últimos 7 dias vs. 7 dias anteriores
* Exibe "+15%" ou "-8%" com seta para cima/baixo
* Substitui o campo de descrição

**Date Range**

* Filtra pela data de criação
* Opções: Today, 1, 7, 14, 30, 60, 90, 180, 365 days

**Conditions** (opcional)

* Adicione filtros para refinar os dados
* Múltiplas condições combinadas com AND
* Veja a seção [Filtering Data](#filtering-data)

### Exemplos

**Total Calls**
Aggregation: COUNT
Table: calls
Label: "Total Calls"
Description: "Last 30 days"
Color: primary
Date Range: 30 days

**Average Call Duration**
Aggregation: AVG
Table: calls
Column: duration
Label: "Avg Duration"
Color: info
Show Mini Chart: Yes
Date Range: 30 days

**Successful Appointments**
Aggregation: COUNT
Table: calls
Label: "Appointments Booked"
Color: success
Compare: Yes
Date Range: 7 days
Conditions:

status = completed

evaluation.appointment\_booked = true

## Widgets de Gráfico (Chart)

Visualize tendências com 8 tipos de gráfico.

### Etapa 1: Básico

O mesmo que widgets de Estatística, mais:

**Tipo de Gráfico**

* `line` - Tendências ao longo do tempo
* `bar` - Comparar categorias ou períodos
* `area` - Gráfico de tendência preenchido
* `pie` - Proporções (requer Group By)
* `donut` - Pizza com furo no centro (requer Group By)
* `polarArea` - Circular com raio variável (requer Group By)
* `radar` - Comparação multi-eixo
* `radialBar` - Indicador único de progresso

### Etapa 2: Exibição e Filtros

**Label** (obrigatório)

* Título do gráfico

**Description**

* Subtítulo opcional abaixo do gráfico
* Exemplo: "Last 30 days performance"

**Color**

* Cor principal do gráfico
* Para pie/donut, usa uma paleta multicolorida (azul, verde, laranja, vermelho, roxo, rosa)

**Date Range**

* Igual ao de estatísticas

**Group By** OU **Group By Period** (mutuamente exclusivos)

**Group By** - Agrupamento categórico

* Agrupa dados por valores de coluna
* Exemplos: Status, Campaign Id, Assistant Name
* **Obrigatório** para gráficos pie/donut/polarArea
* Opcional para bar/radar
* **Não pode usar** com Group By Period

**Group By Period** - Agrupamento por tempo

* Agrupa por “baldes” de tempo
* Opções: hour, day, week, month
* Usado para line/bar/area
* **Não pode usar** com Group By

**Conditions**

* Igual ao de estatísticas

### Etapa 3: Avançado (Somente Gráficos)

**Show Grid Lines** (apenas line/bar/area)

* Linhas horizontais/verticais no fundo
* Ajuda a ler valores exatos
* Padrão: Yes

**Show Legend**

* Rótulos com cores
* Padrão: Yes para pie/donut/polarArea, No para outros
* Posição: parte inferior do gráfico

**Show Tooltips**

* Popups ao passar o mouse com valores exatos
* Padrão: Yes (recomendado)

**Show Data Labels**

* Valores exibidos diretamente nos elementos do gráfico
* Padrão: Yes para pie/donut/polarArea, No para outros
* Pode poluir line/bar

**Show Toolbar** (apenas line/bar/area)

* Controles de zoom e download
* Padrão: No

**Line Curve** (apenas line/area)

* `smooth` - Curvas arredondadas (padrão, visual)
* `straight` - Linhas diretas (preciso)
* `stepline` - Em degraus (eventos discretos)

**Line Width** (apenas line/bar/area)

* Espessura em pixels (1-10)
* Padrão: 2px

**Chart Height**

* Altura em pixels (200-800)
* Padrão: 300px
* Gráficos mais altos ajudam com mais pontos

**Enable Gradient** (apenas radialBar)

* Efeito de gradiente
* Padrão: No

**Gradient Color** (se gradiente ativado)

* Cor final do gradiente
* Padrão: Verde (#10b981)

### Guia de Tipos de Gráfico

**Line Chart**

* **Use para:** Tendências diárias/semanais, dados contínuos
* **Requer:** Group By Period
* **Exemplo:** Calls per day last 30 days

**Bar Chart**

* **Use para:** Comparação de categorias, períodos de tempo
* **Pode usar:** Group By (categorias) OU Group By Period (tempo)
* **Exemplo:** Calls per campaign, hourly distribution

**Area Chart**

* **Use para:** Igual ao line, enfatiza volume
* **Requer:** Group By Period
* **Exemplo:** Call volume trend

**Pie/Donut Chart**

* **Use para:** Proporções, percentuais
* **Requer:** Group By (NÃO Group By Period)
* **Exemplo:** Call status breakdown

**Polar Area**

* **Use para:** Como pie, mas mostra magnitude via raio
* **Requer:** Group By
* **Exemplo:** Campaign contribution

**Radar Chart**

* **Use para:** Comparação multi-variável
* **Requer:** Group By
* **Exemplo:** Performance across metrics

**Radial Bar**

* **Use para:** Percentual/progresso único
* **Não usa:** Group By ou Group By Period
* **Exemplo:** Goal completion %

### Exemplos

**Daily Call Volume (Line)**
Table: calls
Aggregation: COUNT
Chart Type: line
Label: "Daily Calls"
Group By Period: day
Show Grid: Yes
Stroke Curve: smooth
Date Range: 30 days

**Status Breakdown (Pie)**
Table: calls
Aggregation: COUNT
Chart Type: pie
Label: "Call Status"
Group By: status
Show Legend: Yes
Show Data Labels: Yes
Date Range: 7 days

**Hourly Pattern (Bar)**
Table: calls
Aggregation: COUNT
Chart Type: bar
Label: "Calls By Hour"
Group By Period: hour
Date Range: 7 days

**Campaign Comparison (Bar)**
Table: calls
Aggregation: COUNT
Chart Type: bar
Label: "Calls Per Campaign"
Group By: campaign.name
Date Range: 30 days

## Widgets de Tabela (Table)

Exiba registros detalhados com colunas personalizadas.

### Etapa 1: Básico

**Tabela de Dados**

* Escolha a fonte: calls, leads, campaigns, assistants, phone\_numbers, sms

**Campaign Filter** (apenas tabela de leads)

* Selecione a campanha para:
  * Filtrar a tabela para aquela campanha
  * Habilitar colunas de variáveis personalizadas
* Opcional

**Assistant Filter** (apenas tabela de calls)

* Selecione o assistente para:
  * Filtrar a tabela para aquele assistente
  * Habilitar colunas de campos de avaliação
* Opcional

**Seleção de Colunas**

* Colunas básicas: Id, Status, Created At, etc.
* Colunas de relacionamento: Assistant Name, Campaign Name
* Campos de avaliação: evaluation.{field_name} (se assistente selecionado)
* Variáveis do lead: variables.{variable_name} (se campanha selecionada)
* Padrão se nenhuma selecionada: Id, Status, Created At

### Etapa 2: Exibição e Filtros

**Label** (obrigatório)

* Cabeçalho da tabela

**Description**

* Subtítulo opcional

**Date Range**

* Igual ao de estatísticas/gráficos

**Sort By**

* Coluna padrão de ordenação
* Apenas colunas simples (não relacionamentos)
* Padrão: created\_at

**Sort Direction**

* desc (mais recentes primeiro) - padrão
* asc (mais antigos primeiro)

**Rows Per Page**

* Número de linhas para exibir (1-100)
* Padrão: 10

**Conditions**

* Igual ao de estatísticas/gráficos

### Recursos Interativos

**Clickable Rows**

* Linhas são clicáveis
* Direciona automaticamente para a página de detalhe/edição do registro
* Funciona para: Calls, Leads, Campaigns, Assistants

**Live Date Filter**

* Altere o intervalo de datas diretamente no widget
* Substitui o intervalo padrão configurado
* Útil para explorar períodos diferentes

**Status Filter**

* Dropdown multi-seleção para filtrar por status
* Disponível para: Calls, Leads, Campaigns, Assistants, SMS
* Selecione múltiplos status ao mesmo tempo

**Text Display**

* Textos longos são truncados automaticamente em 50 caracteres
* Passar o mouse mostra o conteúdo completo em tooltip

### Tipos de Coluna

**Colunas de Número de Telefone**

* Formato internacional (+1 555 123 4567)
* Bandeira do país como prefixo
* Exemplos: client\_phone\_number, phone\_number

**Colunas de Status**

* Badges coloridos
* Exemplos: status em qualquer tabela

**Colunas de Data**

* Formato "há 3 horas"
* Hover mostra data/hora completa
* Exemplos: created\_at, updated\_at

**Colunas de Avaliação** (tabela calls com assistente)

* Campos booleanos: check ou X com badge verde/vermelho
* Campos não booleanos: valor com badge cinza
* Hover mostra descrição do campo
* Formato: evaluation.{field_name}

**Colunas de Variáveis** (tabela leads com campanha)

* Dados personalizados do lead
* Formato: variables.{variable_name}
* Exemplos: customer\_name, company

**Colunas de Relacionamento**

* Acesso a dados relacionados
* Exemplos: Assistant Name, Campaign Name
* Não é possível ordenar por elas

### Exemplos

**Recent Calls**
Table: calls
Columns:

Client Phone Number

Assistant Name

Duration

Status

Created At
Sort: Created At desc
Rows: 25
Date Range: 7 days

**Successful Appointments**
Table: calls
Assistant: \[Select to load fields]
Columns:

Client Phone Number

Assistant Name

evaluation.appointment\_booked

Created At
Sort: Created At desc
Rows: 50
Date Range: 30 days
Conditions:

Status = completed

Column: Extracted Variables
Extracted Variable Name: Custom variable
Custom Variable Name: appointment\_booked
Operator: =
Variable Value: true

## Filtragem de Dados

Todos os widgets suportam condições para filtrar dados.

### Operadores

* `=` - Igual
* `!=` - Diferente
* `>` - Maior que
* `>=` - Maior ou igual
* `<` - Menor que
* `<=` - Menor ou igual
* `like` - Contém texto
* `in` - Um de (separado por vírgulas)
* `not in` - Não é um de
* `is null` - Sem valor
* `is not null` - Com valor

### Filtragem Básica

**Filtro por Status**
Column: Status
Operator: =
Value: completed

**Filtro por Duração**
Column: Duration
Operator: >
Value: 60

**Múltiplos Valores**
Column: Status
Operator: in
Value: completed,in-progress

### Filtragem por Campo de Avaliação

Filtre por valores de avaliação pós-chamada.

**Configuração:**

1. Column: Extracted Variables
2. Extracted Variable Name: Status ou Custom variable
3. Se Custom variable: informe o nome em Custom Variable Name
4. Variable Value: true/false para booleanos, ou any + valor customizado

**Exemplo Booleano - Appointment Booked**
Column: Extracted Variables
Extracted Variable Name: Custom variable
Custom Variable Name: appointment\_booked
Operator: =
Variable Value: true

**Exemplo Não-Booleano - Sentiment**
Column: Extracted Variables
Extracted Variable Name: Custom variable
Custom Variable Name: sentiment
Operator: =
Variable Value: any
Custom Value: positive

**Verificar se Campo Existe**
Column: Extracted Variables
Extracted Variable Name: Custom variable
Custom Variable Name: interested
Operator: =
Variable Value: any

### Múltiplas Condições

Condições são combinadas com AND:

Filter for successful long calls:
Condition 1:

Column: Status

Operator: =

Value: completed

Condition 2:

Column: Duration

Operator: >

Value: 120

Condition 3:

Column: Extracted Variables

Extracted Variable Name: Custom variable

Custom Variable Name: appointment\_booked

Operator: =

Variable Value: true

## Melhores Práticas

### Nomeação de Widgets

Use nomes internos descritivos:

* ✅ "Sales Calls - Last 30 Days"
* ✅ "Support Duration Average"
* ❌ "Widget 1"

### Intervalos de Data

Combine o intervalo ao caso de uso:

* **Today:** Monitoramento em tempo real
* **7 days:** Performance semanal
* **30 days:** Tendências mensais
* **90+ days:** Análise de longo prazo

### Cores

Uso estratégico de cores:

* **Verde (success):** Métricas positivas
* **Vermelho (danger):** Métricas de alerta
* **Azul (primary):** Métricas neutras
* **Amarelo (warning):** Atenção necessária
* **Cinza (info):** Info secundária

### Performance

Mantenha dashboards rápidos:

* Use filtros por intervalo de data
* Limite widgets por dashboard a menos de 20
* Use COUNT quando possível (mais rápido)
* Evite intervalos muito longos

## Solução de Problemas

**Widget mostra "No data"**

* Amplie o intervalo de datas
* Remova/ajuste filtros
* Verifique se a tabela tem registros

**Campos de avaliação não aparecem**

* Selecione o assistente na configuração do widget
* Garanta que o assistente tenha schema pós-chamada
* Verifique se os nomes dos campos batem

**Gráfico aparece vazio**

* Pie/donut: Deve usar Group By (não Period)
* Line/area: Deve usar Group By Period (não Category)
* Verifique se o intervalo de datas tem dados

**Tabela sem colunas**

* Colunas de relacionamento exigem registros relacionados
* Colunas de avaliação exigem seleção do assistente
* Colunas de variáveis exigem seleção de campanha

**Erro "Group By required"**

* Gráficos pie/donut/polarArea DEVEM ter Group By
* Não é possível usar Group By Period com esses tipos

**Não dá para ordenar por coluna**

* Colunas de relacionamento (com .) não ordenáveis
* Campos de avaliação não ordenáveis
* Use colunas básicas para ordenar

<Note>
  Para criação de dashboards e gerenciamento de layout, veja [Visão Geral de Dashboards Personalizados](/custom-dashboards/overview).
</Note>