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

# Consultas

> Modulo de Consultas SQL para analisis de datos

El modulo de **Consultas** te permite ejecutar consultas SQL directamente sobre los datos sincronizados de tu workspace. Es una herramienta para analizar contactos, mensajes, oportunidades, campanas y mas, sin necesidad de herramientas externas.

<Tip>
  Solo se permiten consultas de tipo **SELECT**. No es posible modificar, insertar o eliminar datos desde este modulo.
</Tip>

## Interfaz del Editor

El modulo cuenta con las siguientes secciones:

* **Sidebar izquierdo**: Lista de tablas disponibles y consultas guardadas
* **Editor SQL**: Editor de codigo con resaltado de sintaxis SQL
* **Panel de resultados**: Tabla con los resultados de la consulta
* **Barra de acciones**: Botones para sincronizar datos, ejecutar y exportar

### Atajos de teclado

| Atajo                    | Accion            |
| ------------------------ | ----------------- |
| `Cmd + Enter` (Mac)      | Ejecutar consulta |
| `Ctrl + Enter` (Windows) | Ejecutar consulta |

### Tabs multiples

Puedes abrir multiples consultas en tabs separados. Haz doble clic en el nombre del tab para renombrarlo.

### Consultas guardadas

Presiona el boton de guardar para almacenar una consulta. Las consultas guardadas aparecen en el sidebar izquierdo y se pueden cargar haciendo clic sobre ellas.

## Sincronizacion de datos

Los datos se sincronizan desde la base de datos principal de Plazbot hacia una base de datos analitica. Para actualizar los datos:

1. Haz clic en **Sincronizar datos** en la barra superior
2. Espera a que el proceso termine (se muestra el progreso en tiempo real)
3. Una vez completado, los datos estaran actualizados

<Tip>
  Los mensajes se sincronizan de los ultimos **30 dias**. Los contactos, oportunidades y demas datos se sincronizan completamente.
</Tip>

## Tablas disponibles

El modulo expone 6 tablas para consultas:

| Tabla           | Descripcion                                      |
| --------------- | ------------------------------------------------ |
| `contacts`      | Contactos del workspace                          |
| `messages`      | Mensajes de conversaciones                       |
| `conversations` | Envios de mensajes (campanas, individuales, API) |
| `opportunities` | Oportunidades de negocio                         |
| `users`         | Usuarios/agentes del workspace                   |
| `campaigns`     | Campanas de envio masivo                         |

***

### Tabla: contacts

Contiene todos los contactos del workspace.

| Campo                      | Tipo      | Descripcion                              |
| -------------------------- | --------- | ---------------------------------------- |
| `id`                       | text      | ID unico del contacto                    |
| `name`                     | text      | Nombre                                   |
| `lastname`                 | text      | Apellido                                 |
| `fullname`                 | text      | Nombre completo                          |
| `alias`                    | text      | Alias del contacto                       |
| `email`                    | text      | Correo electronico                       |
| `phone`                    | text      | Telefono principal                       |
| `phone2`                   | text      | Telefono secundario                      |
| `phone3`                   | text      | Tercer telefono                          |
| `platform_id`              | integer   | Plataforma de origen (ver valores abajo) |
| `platform_sender_id`       | text      | ID del contacto en la plataforma externa |
| `assigned_agent_id`        | text      | ID del agente asignado                   |
| `assigned_agent_name`      | text      | Nombre del agente asignado               |
| `assigned_agent_date`      | timestamp | Fecha de asignacion del agente           |
| `stage_id`                 | text      | ID de la fase/etapa                      |
| `stage_name`               | text      | Nombre de la fase                        |
| `segmentation_id`          | text      | ID de la segmentacion                    |
| `segmentation_name`        | text      | Nombre de la segmentacion                |
| `is_solved`                | boolean   | Si esta resuelto                         |
| `solved_by_agent_id`       | text      | ID del agente que resolvio               |
| `solved_by_agent_name`     | text      | Nombre del agente que resolvio           |
| `solved_date`              | timestamp | Fecha de resolucion                      |
| `is_read`                  | boolean   | Si fue leido                             |
| `is_archived`              | boolean   | Si esta archivado                        |
| `is_bot_enabled`           | boolean   | Si el bot esta habilitado                |
| `is_blocked`               | boolean   | Si esta bloqueado                        |
| `is_show_in_chat`          | boolean   | Si se muestra en el chat                 |
| `is_manually_added`        | boolean   | Si fue agregado manualmente              |
| `tags`                     | jsonb     | Etiquetas asignadas                      |
| `variables`                | jsonb     | Variables del contacto                   |
| `last_message`             | text      | Contenido del ultimo mensaje             |
| `last_message_date`        | timestamp | Fecha del ultimo mensaje                 |
| `first_message`            | text      | Contenido del primer mensaje             |
| `first_message_date`       | timestamp | Fecha del primer mensaje                 |
| `first_agent_message_date` | timestamp | Fecha del primer mensaje de un agente    |
| `document_number`          | text      | Numero de documento (DNI, RUC, etc.)     |
| `business_name`            | text      | Nombre de empresa                        |
| `creation_date`            | timestamp | Fecha de creacion                        |
| `reject_reason_content`    | text      | Motivo de rechazo                        |
| `reject_reason_date`       | timestamp | Fecha de rechazo                         |
| `color`                    | text      | Color asignado al contacto               |
| `sentiment`                | text      | Sentimiento detectado                    |

**Valores de `platform_id`:**

| Valor | Plataforma     |
| ----- | -------------- |
| 1     | Webchat        |
| 2     | WhatsApp       |
| 3     | Facebook       |
| 4     | Instagram      |
| 5     | Telegram       |
| 6     | Portal         |
| 7     | Code           |
| 8     | Calls          |
| 9     | Facebook Leads |
| 10    | Tickos         |

***

### Tabla: messages

Contiene todos los mensajes de las conversaciones.

| Campo                     | Tipo      | Descripcion                                                   |
| ------------------------- | --------- | ------------------------------------------------------------- |
| `id`                      | text      | ID unico del mensaje                                          |
| `contact_id`              | text      | ID del contacto asociado                                      |
| `content`                 | text      | Contenido del mensaje                                         |
| `type`                    | text      | Tipo de contenido (TEXT, IMAGE, AUDIO, VIDEO, DOCUMENT, etc.) |
| `origin_message`          | text      | Origen del mensaje (ver valores abajo)                        |
| `answer_type`             | integer   | Quien respondio (ver valores abajo)                           |
| `answer_type_text`        | text      | Texto descriptivo de answer\_type                             |
| `answer_agent_id`         | text      | ID del agente que respondio                                   |
| `answer_agent_name`       | text      | Nombre del agente que respondio                               |
| `platform_id`             | text      | Plataforma                                                    |
| `sentiment`               | text      | Sentimiento detectado                                         |
| `template_code`           | text      | Codigo del template usado                                     |
| `campaign_name`           | text      | Nombre de la campana asociada                                 |
| `campaign_id`             | text      | ID de la campana asociada                                     |
| `f_type`                  | integer   | Tipo de mensaje (ver valores abajo)                           |
| `is_note`                 | boolean   | Si es nota interna                                            |
| `message_status_id`       | integer   | Estado del mensaje                                            |
| `message_whatsapp_id`     | text      | ID del mensaje en WhatsApp                                    |
| `content_url`             | text      | URL del archivo adjunto                                       |
| `content_type`            | text      | MIME type del contenido                                       |
| `content_filename`        | text      | Nombre del archivo adjunto                                    |
| `sent_message_error`      | text      | Error al enviar                                               |
| `sent_message_error_code` | text      | Codigo de error al enviar                                     |
| `ia_provider`             | text      | Proveedor de IA (openai, claude, gemini)                      |
| `ia_model`                | text      | Modelo de IA usado                                            |
| `ia_input_tokens`         | integer   | Tokens de entrada consumidos                                  |
| `ia_output_tokens`        | integer   | Tokens de salida generados                                    |
| `ia_estimated_cost_usd`   | decimal   | Costo estimado en USD                                         |
| `ia_iterations`           | integer   | Iteraciones del agentic loop                                  |
| `ia_tool_calls_count`     | integer   | Cantidad de llamadas a herramientas                           |
| `ia_latency_ms`           | bigint    | Latencia en milisegundos                                      |
| `ia_agent_id`             | text      | ID del agente IA                                              |
| `ia_agent_name`           | text      | Nombre del agente IA                                          |
| `ia_feedback_rating`      | integer   | Rating: 1 = positivo, -1 = negativo                           |
| `ia_tools_executed`       | jsonb     | Herramientas ejecutadas por IA                                |
| `automation_info`         | jsonb     | Informacion de la automatizacion                              |
| `context_message_id`      | text      | ID del mensaje al que se responde (reply)                     |
| `context_message_content` | text      | Contenido del mensaje al que se responde                      |
| `reference1`              | text      | Referencia 1 (webhooks)                                       |
| `reference2`              | text      | Referencia 2 (webhooks)                                       |
| `reference3`              | text      | Referencia 3 (webhooks)                                       |
| `creation_date`           | timestamp | Fecha de creacion                                             |

**Valores de `f_type` (tipo de mensaje):**

| Valor | Significado                            |
| ----- | -------------------------------------- |
| 1     | Bot (mensaje del flujo/automatizacion) |
| 2     | Contact (mensaje del contacto)         |
| 3     | InternalNote (nota interna)            |
| 4     | ChatEvent (evento de chat)             |
| 5     | CallResumen (resumen de llamada)       |

**Valores de `answer_type` (quien respondio):**

| Valor | Significado                        |
| ----- | ---------------------------------- |
| 1     | FLOW (respondio la automatizacion) |
| 2     | AGENT (respondio un agente humano) |
| 3     | AGENT\_IA (respondio un agente IA) |

**Valores de `origin_message`:**

| Valor        | Significado                |
| ------------ | -------------------------- |
| `me`         | Enviado por el negocio     |
| `contact`    | Enviado por el cliente     |
| `automation` | Enviado por automatizacion |
| `agent`      | Enviado por un agente      |

***

### Tabla: conversations

Registra los envios de mensajes (campanas, individuales y via API).

| Campo                      | Tipo      | Descripcion                             |
| -------------------------- | --------- | --------------------------------------- |
| `id`                       | text      | ID unico                                |
| `contact_id`               | text      | ID del contacto destinatario            |
| `template_code`            | text      | Codigo del template de WhatsApp         |
| `template_type`            | text      | Tipo de template                        |
| `send_type`                | integer   | Tipo de envio (ver valores abajo)       |
| `send_type_text`           | text      | Texto descriptivo de send\_type         |
| `response_status`          | integer   | Estado de respuesta (ver valores abajo) |
| `response_status_text`     | text      | Texto descriptivo de response\_status   |
| `campaign_name`            | text      | Nombre de la campana                    |
| `campaign_id`              | text      | ID de la campana                        |
| `agent_sender_id`          | text      | ID del agente que envio                 |
| `agent_sender_name`        | text      | Nombre del agente que envio             |
| `platform_id`              | text      | Plataforma de envio                     |
| `platform_sender_id`       | text      | ID del sender en la plataforma          |
| `internal_whatsapp_number` | text      | Numero de WhatsApp del negocio          |
| `is_scheduled`             | boolean   | Si fue un envio programado              |
| `scheduled_at`             | timestamp | Fecha programada de envio               |
| `request_body`             | text      | Body de la solicitud a la API           |
| `response_body`            | text      | Body de respuesta de la API             |
| `response_status_body`     | text      | Status body de respuesta                |
| `sent_date`                | timestamp | Fecha de envio                          |
| `creation_date`            | timestamp | Fecha de creacion                       |

**Valores de `send_type`:**

| Valor | Significado                   |
| ----- | ----------------------------- |
| 1     | CAMPAIGN (envio de campana)   |
| 2     | INDIVIDUAL (envio individual) |
| 3     | API (envio via API)           |

**Valores de `response_status`:**

| Valor | Significado                      |
| ----- | -------------------------------- |
| 1     | ACCEPTED (aceptado por WhatsApp) |
| 2     | ERROR (error en el envio)        |
| 3     | PENDING (pendiente)              |

***

### Tabla: opportunities

Contiene las oportunidades de negocio del pipeline.

| Campo                 | Tipo      | Descripcion                       |
| --------------------- | --------- | --------------------------------- |
| `id`                  | text      | ID unica                          |
| `contact_id`          | text      | ID del contacto asociado          |
| `name`                | text      | Nombre de la oportunidad          |
| `opport_code`         | text      | Codigo de la oportunidad          |
| `amount`              | decimal   | Monto inicial                     |
| `final_amount`        | decimal   | Monto final                       |
| `currency_code`       | text      | Codigo de moneda (USD, PEN, etc.) |
| `currency_symbol`     | text      | Simbolo de moneda (\$, S/, etc.)  |
| `stage_id`            | text      | ID de la etapa en el pipeline     |
| `stage_name`          | text      | Nombre de la etapa                |
| `pipeline_id`         | text      | ID del pipeline                   |
| `pipeline_name`       | text      | Nombre del pipeline               |
| `assigned_agent_id`   | text      | ID del agente asignado            |
| `assigned_agent_name` | text      | Nombre del agente asignado        |
| `status`              | integer   | Estado (ver valores abajo)        |
| `close_date`          | timestamp | Fecha de cierre                   |
| `creation_date`       | timestamp | Fecha de creacion                 |
| `activities`          | jsonb     | Actividades asociadas             |

**Valores de `status`:**

| Valor | Significado |
| ----- | ----------- |
| 0     | Sin definir |
| 1     | Ganada      |
| 2     | Perdida     |

***

### Tabla: users

Contiene los usuarios y agentes del workspace.

| Campo       | Tipo    | Descripcion                   |
| ----------- | ------- | ----------------------------- |
| `id`        | text    | ID del usuario                |
| `name`      | text    | Nombre                        |
| `last_name` | text    | Apellido                      |
| `email`     | text    | Correo electronico            |
| `role`      | text    | Rol: owner, supervisor, agent |
| `is_online` | boolean | Si esta en linea              |
| `status`    | text    | Estado: active, deactivated   |
| `timezone`  | text    | Zona horaria                  |

***

### Tabla: campaigns

Contiene las campanas de envio masivo.

| Campo                    | Tipo      | Descripcion                                  |
| ------------------------ | --------- | -------------------------------------------- |
| `id`                     | text      | ID de la campana                             |
| `name`                   | text      | Nombre                                       |
| `status_id`              | integer   | Estado (ver valores abajo)                   |
| `status_text`            | text      | Texto descriptivo del estado                 |
| `total_records`          | integer   | Total de contactos                           |
| `total_send`             | integer   | Total de mensajes enviados                   |
| `total_errors`           | integer   | Total de errores                             |
| `success_rate`           | decimal   | Tasa de exito (%)                            |
| `is_direct_send`         | boolean   | Si es envio directo (sin programar)          |
| `scheduled_send_date`    | timestamp | Fecha programada de envio                    |
| `agent_sender_name`      | text      | Nombre del agente que envio                  |
| `user_creation`          | text      | Usuario que creo la campana                  |
| `show_messages_in_chat`  | boolean   | Si los mensajes se muestran en chat          |
| `ia_agent_start_enabled` | boolean   | Si el agente IA se activa al responder       |
| `random_agent_enabled`   | boolean   | Si se asigna agente aleatorio                |
| `cancellation_date`      | timestamp | Fecha de cancelacion                         |
| `error_summary`          | text      | Resumen de errores                           |
| `templates`              | jsonb     | Templates usados                             |
| `tags`                   | jsonb     | Etiquetas asignadas a contactos              |
| `filters`                | jsonb     | Filtros aplicados para seleccionar contactos |
| `creation_date`          | timestamp | Fecha de creacion                            |
| `last_updated_date`      | timestamp | Ultima actualizacion                         |

**Valores de `status_id`:**

| Valor | Significado           |
| ----- | --------------------- |
| 1     | PENDING (pendiente)   |
| 2     | SCHEDULED (agendada)  |
| 3     | SENDING (enviando)    |
| 4     | COMPLETE (completada) |
| 5     | ERROR (error)         |
| 6     | CANCELED (cancelada)  |

***

## Ejemplos de consultas

### Contactos creados en un rango de fechas

```sql theme={null}
SELECT fullname, email, phone, creation_date
FROM contacts
WHERE creation_date >= '2025-01-01'
  AND creation_date < '2025-02-01'
ORDER BY creation_date DESC
LIMIT 100;
```

### Buscar contacto por nombre

```sql theme={null}
SELECT *
FROM contacts
WHERE fullname ILIKE '%nombre%'
LIMIT 50;
```

### Mensajes de un contacto especifico

```sql theme={null}
SELECT m.content, m.creation_date, m.f_type
FROM messages m
JOIN contacts c ON c.id = m.contact_id
WHERE c.fullname ILIKE '%nombre%'
ORDER BY m.creation_date DESC
LIMIT 100;
```

### Campanas en envio

```sql theme={null}
SELECT name, status_text, total_records, total_send,
       total_errors, success_rate
FROM campaigns
WHERE status_text = 'SENDING'
ORDER BY creation_date DESC;
```

### Oportunidades por pipeline

```sql theme={null}
SELECT name, amount, final_amount, pipeline_name,
       stage_name, assigned_agent_name, status
FROM opportunities
ORDER BY creation_date DESC
LIMIT 100;
```

### Contactos con un tag especifico

```sql theme={null}
SELECT fullname, email, tags
FROM contacts
WHERE tags::text ILIKE '%nombre_tag%'
LIMIT 100;
```

### Contactos sin agente asignado

```sql theme={null}
SELECT fullname, email, creation_date
FROM contacts
WHERE assigned_agent_name IS NULL
ORDER BY creation_date DESC
LIMIT 100;
```

### Mensajes respondidos por agente IA

```sql theme={null}
SELECT m.content, m.ia_agent_name, m.ia_model,
       m.ia_estimated_cost_usd, m.creation_date
FROM messages m
WHERE m.ia_agent_name IS NOT NULL
ORDER BY m.creation_date DESC
LIMIT 100;
```

### JOIN contactos con oportunidades

```sql theme={null}
SELECT c.fullname, c.email, o.name AS oportunidad,
       o.amount, o.stage_name, o.pipeline_name
FROM contacts c
JOIN opportunities o ON o.contact_id = c.id
ORDER BY o.creation_date DESC
LIMIT 100;
```

### Conversaciones de una campana

```sql theme={null}
SELECT campaign_name, agent_sender_name,
       response_status_text, sent_date
FROM conversations
WHERE campaign_name IS NOT NULL
ORDER BY sent_date DESC
LIMIT 100;
```

### Costo total de IA por agente

```sql theme={null}
SELECT ia_agent_name,
       COUNT(*) AS total_mensajes,
       SUM(ia_estimated_cost_usd) AS costo_total_usd,
       AVG(ia_latency_ms) AS latencia_promedio_ms
FROM messages
WHERE ia_agent_name IS NOT NULL
GROUP BY ia_agent_name
ORDER BY costo_total_usd DESC;
```

## Exportacion de resultados

Los resultados pueden exportarse en multiples formatos desde el boton **Export**:

| Formato          | Descripcion                                        |
| ---------------- | -------------------------------------------------- |
| Copy as Markdown | Copia la tabla en formato Markdown al portapapeles |
| Copy as JSON     | Copia los datos como JSON al portapapeles          |
| Copy as CSV      | Copia los datos como CSV al portapapeles           |
| Download CSV     | Descarga un archivo .csv                           |
| Download .sql    | Descarga la consulta como archivo .sql             |