Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/banredco/helpdesk/llms.txt

Use this file to discover all available pages before exploring further.

La integración con Google Workspace utiliza la Gmail API a través de una cuenta de servicio con delegación de dominio, lo que significa que el helpdesk puede leer y enviar correos en nombre de cualquier cuenta de tu organización sin necesidad de contraseñas IMAP ni SMTP. Este enfoque usa el protocolo OAuth2, es más estable y seguro que IMAP, y es la opción recomendada por el sistema para organizaciones que utilizan Google Workspace. En el formulario de creación, cuando seleccionas el tipo “Google Workspace”, los campos de servidor IMAP y SMTP quedan ocultos y solo necesitas ingresar la dirección de correo.

​
Requisitos previos

Antes de configurar el buzón en el helpdesk, debes completar la configuración del lado de Google:
  • Acceso de administrador a la consola de Google Workspace de tu organización.
  • Un proyecto activo en Google Cloud Console con la Gmail API habilitada.
  • Una cuenta de servicio creada en ese proyecto, con su archivo de clave en formato JSON descargado.
  • Delegación de dominio configurada en la consola de administración de Google Workspace, para que la cuenta de servicio pueda impersonar a las cuentas de correo de la organización.

​
Configurar la integración paso a paso

1

Crear un proyecto en Google Cloud Console

Accede a console.cloud.google.com. Si ya tienes un proyecto dedicado para el helpdesk, puedes utilizarlo directamente. De lo contrario, crea uno nuevo desde Seleccionar proyecto → Nuevo proyecto e ingresa un nombre descriptivo como Banred Helpdesk.
2

Habilitar la Gmail API

Dentro del proyecto, ve a APIs y servicios → Biblioteca. Busca Gmail API y haz clic en Habilitar. Sin este paso, cualquier llamada a la API retornará un error 403.
3

Crear la cuenta de servicio y descargar la clave JSON

Ve a APIs y servicios → Credenciales → Crear credenciales → Cuenta de servicio. Completa el formulario con un nombre y descripción. Una vez creada, abre la cuenta de servicio, ve a la pestaña Claves → Agregar clave → Crear nueva clave y selecciona el formato JSON. El archivo se descargará automáticamente. Guárdalo en un lugar seguro: es el único que podrás descargar.
4

Configurar la delegación de dominio

La delegación de dominio permite que la cuenta de servicio actúe en nombre de usuarios reales de tu organización.
  1. En Google Cloud Console, abre la cuenta de servicio recién creada y copia el valor de ID de cliente (un número largo).
  2. Accede a la Consola de Administración de Google Workspace en admin.google.com.
  3. Ve a Seguridad → Control y gestión de acceso → Controles de API → Delegación en todo el dominio → Administrar la delegación en todo el dominio.
  4. Haz clic en Agregar nuevo e ingresa el ID de cliente copiado en el paso anterior.
  5. En el campo de alcances (scopes), agrega exactamente el siguiente valor:
https://www.googleapis.com/auth/gmail.modify
Este scope es el que usa GmailService::getClient() para autenticarse y permite leer, modificar y enviar correos en nombre del usuario impersonado.
5

Colocar el archivo JSON en el servidor

Copia el archivo de clave JSON de la cuenta de servicio al servidor donde está instalado el helpdesk. La ruta exacta que lee GmailService es:
/var/www/helpdesk_ban/data/private/google-workspace.json
Asegúrate de que el archivo sea legible por el usuario del servidor web (habitualmente www-data) pero que no sea accesible desde el navegador. Verifica que el directorio data/private/ esté protegido con las reglas de .htaccess o la configuración de Nginx correspondiente.
# Establecer permisos seguros para el archivo de clave
chown www-data:www-data /var/www/helpdesk_ban/data/private/google-workspace.json
chmod 600 /var/www/helpdesk_ban/data/private/google-workspace.json
6

Crear el buzón en el helpdesk

Con el archivo JSON en su lugar, ve a Admin → Configuración → Correos → Nuevo Correo y completa el formulario:
  • Tipo de conexión: selecciona Google Workspace (Recomendado).
  • Correo electrónico: ingresa la dirección de correo de la cuenta de Workspace que quieres vincular (ej. soporte@tuempresa.com). Este valor es el que se pasará como $email a GmailService::getClient() para la impersonación.
  • Nombre remitente, Reply-To, Grupo asignado y Opciones: completa estos campos igual que en cualquier otro buzón.
Los bloques de configuración IMAP y SMTP quedan ocultos automáticamente cuando seleccionas este tipo de conexión.
7

Probar y activar el buzón

Guarda el buzón y luego haz clic en el botón de prueba (ícono de enchufe). mailbox-test.php llamará a GmailService::testConnection($email), que intenta listar las etiquetas del buzón vía la API. Si todo está correcto, verás ✅ Gmail API OK. Si hay un error de delegación, scope o ruta al JSON, verás ❌ Gmail API ERROR y el detalle quedará registrado en el error_log del servidor.

​
Cómo funciona el procesamiento de correo

El procesamiento de buzones Gmail está implementado en GmailMailboxProcessor y se ejecuta a través de cron/process-gmail.php. El flujo es el siguiente:
  1. El cron consulta todos los buzones activos con connection_type = 'gmail'.
  2. Por cada buzón, GmailMailboxProcessor::processMailbox() llama a GmailService::getMessages(), que recupera hasta 20 mensajes con la etiqueta UNREAD usando listUsersMessages().
  3. Para cada mensaje, se verifica si el gmail_message_id ya existe en la tabla email_imports para evitar duplicados.
  4. Si es nuevo, se llama a GmailService::parseMessage() para extraer asunto, remitente y cuerpo, y a GmailService::getAttachments() para obtener los adjuntos.
  5. Los datos se pasan a EmailProcessor::process(), que determina si se trata de un ticket nuevo o una respuesta a uno existente (buscando el patrón [Ticket #N] en el asunto).
  6. Si el procesamiento es exitoso, se registra el mensaje en email_imports con process_status = 'Procesado'.
  7. Finalmente, GmailService::markAsRead() llama a users_messages->modify() para eliminar la etiqueta UNREAD, evitando que el mensaje sea procesado de nuevo en la siguiente ejecución.
Cron process-gmail.php
      │
      ▼
GmailMailboxProcessor::processMailbox()
      │
      ▼
GmailService::getMessages() → mensajes UNREAD (máx. 20)
      │
      ▼ (por cada mensaje)
¿Existe en email_imports? ─── Sí ──→ Saltar
      │
      No
      │
      ▼
GmailService::parseMessage() + getAttachments()
      │
      ▼
EmailProcessor::process()
      │
      ├─── Ticket nuevo ──→ INSERT tickets + ticket_messages + notificación
      │
      └─── Respuesta    ──→ INSERT ticket_messages + reabrir si corresponde
      │
      ▼
GmailService::markAsRead() → elimina etiqueta UNREAD

​
Configurar el cron job

Para que el procesamiento sea automático, agrega la siguiente línea al crontab del servidor. Con frecuencia de 1 minuto, los tickets se crean casi en tiempo real: 
* * * * * php /var/www/helpdesk_ban/cron/process-gmail.php
Para editar el crontab del usuario www-data: 
sudo crontab -u www-data -e
Se recomienda una frecuencia de 1 minuto (* * * * *) para que los tickets se creen de forma casi inmediata después de que el cliente envía el correo. Frecuencias más largas (ej. cada 5 o 10 minutos) pueden generar demoras perceptibles en la atención al cliente.
La integración con Gmail API no requiere credenciales IMAP ni SMTP. Los bloques de configuración de servidor de entrada y salida quedan ocultos en el formulario cuando connection_type = 'gmail'. Todo el envío y recepción de correos se realiza exclusivamente a través de la Gmail API usando la cuenta de servicio configurada en el archivo google-workspace.json.

Build docs developers (and LLMs) love

Get started for freeTalk to us