FullChat Developer Guide

Arquitectura General

FullChat es una plataforma SaaS multi-tenant de comunicacion omnicanal construida sobre Chatwoot v4.11.0 (Enterprise fork). Soporta 12+ canales de mensajeria, VoIP/PBX integrado, CRM, campanas multicanal y automatizaciones.

Estructura del Proyecto

fullchat/
  app/
    controllers/          # 215 controllers
      api/v1/accounts/    # API principal
      webhooks/           # Webhook handlers (WA, FB, Voice, etc)
    models/               # 78 modelos (Account, Conversation, Contact, etc)
    services/             # 194 service objects
    jobs/                 # 84 background jobs (Sidekiq)
    javascript/
      dashboard/          # Frontend SPA
        components/       # 168 componentes clasicos
        components-next/  # 390 componentes modernos
        routes/           # Pages y routing
        stores/           # Pinia stores (8)
        store/modules/    # Vuex modules (25+)
        plugins/          # fullchatTheme.js (27 temas)
    channels/             # ActionCable (WebSockets)
  config/
    routes.rb             # 609 rutas, 1098 lineas
    initializers/
      zzz_*.rb            # 10 initializers custom FullCall
  db/
    migrate/              # 114 migraciones
  spec/                   # 783 test files (RSpec)
  deployment/             # Systemd + Nginx configs

Stack Tecnologico

Componente	Tecnologia	Version
Lenguaje Backend	Ruby	3.4.4
Framework Backend	Ruby on Rails	7.1.5.2
Base de Datos	PostgreSQL	16.13
Cache / PubSub	Redis	8.6.2
Background Jobs	Sidekiq	7.3+
Web Server	Puma	6.x
Reverse Proxy	Nginx	1.24
Lenguaje Frontend	JavaScript/TypeScript	ES2022
Framework Frontend	Vue.js	3.5.12
Bundler	Vite + vite-plugin-ruby	5.4.21
UI Library	PrimeVue	4.5.4
CSS	Tailwind CSS + UnoCSS	3.x
State Management	Pinia + Vuex	3.0 / 4.x
Testing Backend	RSpec	3.x
Testing Frontend	Vitest + Vue Test Utils	3.0.5
Search	OpenSearch + pgVector	-
AI	OpenAI (ruby-openai, ruby_llm)	GPT-4.1
Auth	Devise + devise_token_auth	-
Authorization	Pundit	-
Feature Flags	FlagShihTzu	-
Payments	Stripe	~18.0
VoIP	Asterisk + FreePBX + PJSIP	17.9.3

Infraestructura (4 Servidores)

Servidor	IP	OS	Rol	Servicios
Production	194.163.184.69	Ubuntu 24.04	FullChat App	Puma, Sidekiq, PostgreSQL 16, Redis 8, Nginx
Dokploy	207.180.234.156	Ubuntu 20.04	Docker Swarm	30 containers: FreePBX, n8n, Evolution API, Twenty CRM, Jitsi, Etherpad, MinIO
Postal	217.76.58.191	Ubuntu 24.04	Email + VoIP	Postal (SMTP), Asterisk 20.18, Kamailio, Nginx
GoIP	186.154.148.252	Firmware	GSM Gateway	GoIP32 - 31 SIMs, llamadas + SMS

Arquitectura de Red

Internet
  |
  +--- Cloudflare (DNS + CDN + SSL)
  |      |
  |      +--- app.fullchat.co ----> 194.163.184.69:443 (Nginx -> Puma:3001)
  |      +--- call.fullchat.co ---> 207.180.234.156:443 (Traefik -> FreePBX:8280)
  |      +--- dev.fullchat.co ----> 207.180.234.156:443 (Traefik -> Docs:8480)
  |      +--- mail.fullchat.co ---> 217.76.58.191:25 (Postal SMTP)
  |      +--- meet.fullchat.co ---> 207.180.234.156:443 (Traefik -> Jitsi:8180)
  |      +--- goip.fullchat.co ---> 207.180.234.156:443 (Traefik -> GoIP:8080)
  |
  +--- SIP/RTP
         +--- GoIP (186.154.148.252:5060) <--> FreePBX (207.180.234.156:5160)
         +--- Postal Asterisk (217.76.58.191:5070) <--> FreePBX

Modulos Custom (FullChat)

Ademas de las funcionalidades nativas de Chatwoot, FullChat agrega 15 modulos custom:

Modulo	Frontend	Backend	Plan Minimo
Centro de Llamadas	CallCenterView.vue	zzz_call_center.rb	Demo
Campanas Multicanal	CampaignsView.vue	zzz_sms_campaigns.rb	Starter
IVR Builder	IvrBuilderView.vue	zzz_ivr_builder.rb	Pro
Voice Bot IA	VoiceBotView.vue	zzz_ai_voice_bot.rb	Enterprise
Predictive Dialer	(en Campanas)	zzz_predictive_dialer.rb	Enterprise
CRM Unificado	CrmView.vue	zzz_crm_integration.rb	Pro
Email Marketing	EmailMarketingView.vue	zzz_fullsend_email.rb	Pro
Automatizaciones	AutomationsHubView.vue	zzz_n8n_automations.rb	Pro
SMS GoIP	(en Campanas)	zzz_sms_campaigns.rb	Starter
Softphone WebRTC	AsteriskSoftphone.vue	levels_controller.rb	Demo
Click-to-Call	ContactInfoRow.vue	(frontend only)	Demo
Webhooks Voz	-	voice_controller.rb	Demo
SaaS Control	SaasAdminV2.vue (6080 lineas)	saas_admin_v2_controller.rb	SuperAdmin
Pipeline CRM	PipelineKanban.vue	deals_controller.rb	Pro
27 Temas	fullchatTheme.js	aaa_theme_inject.rb	Demo

Feature Gating (SaaS Plans)

# Backend check:
Current.account.call_center_enabled?
Current.account.voice_bot_enabled?
Current.account.can_send_goip_sms?
Current.account.fullcall_features_summary

# API endpoint:
GET /api/v1/accounts/:id/training/fullcall_features
GET /api/v1/accounts/:id/training/fullcall_plans_matrix

API Reference

Autenticacion

# Header token:
curl -H "api_access_token: TOKEN" https://app.fullchat.co/api/v1/...

# Obtener token:
POST /auth/sign_in { email, password }
Response: { data: { access_token: "..." } }

Endpoints Principales (609 rutas)

Recurso	Metodo	Ruta	Descripcion
Conversaciones	GET	/api/v1/accounts/:id/conversations	Listar conversaciones
Mensajes	POST	/api/v1/accounts/:id/conversations/:cid/messages	Enviar mensaje
Contactos	GET	/api/v1/accounts/:id/contacts	Listar contactos
Inboxes	GET	/api/v1/accounts/:id/inboxes	Listar canales
Agentes	GET	/api/v1/accounts/:id/agents	Listar agentes
Call Center	GET	/api/v1/accounts/:id/training/call_center_status	Estado PBX en tiempo real
CDR	GET	/api/v1/accounts/:id/training/call_center_cdr	Historial de llamadas
IVR	GET/POST	/api/v1/accounts/:id/training/ivr_config	Leer/guardar IVR
Voice Bot	POST	/api/v1/accounts/:id/training/voice_bot_test	Probar bot IA con texto
SMS	POST	/api/v1/accounts/:id/training/send_sms	Enviar SMS via GoIP
Campanas	POST	/api/v1/accounts/:id/training/campaign_create	Crear campana multicanal
CRM	GET	/api/v1/accounts/:id/training/crm_contacts	Contactos Twenty CRM
Email	POST	/api/v1/accounts/:id/training/email_send	Enviar email via Postal
n8n	GET	/api/v1/accounts/:id/training/automations_list	Workflows n8n
Softphone	GET	/api/v1/accounts/:id/training/voice_config	Config WebRTC SIP
Features	GET	/api/v1/accounts/:id/training/fullcall_features	Features del plan

Webhooks (Publicos)

# FreePBX envia eventos de llamada:
POST /webhooks/voice/incoming   # Llamada entrante -> crea contacto+conversacion
POST /webhooks/voice/event      # Evento (answered, ended, failed)
POST /webhooks/voice/recording  # Grabacion de llamada (file upload)
# Header: X-Voice-Secret: FullCall_Webhook_2026!

Procedimiento de Deploy

Requisitos

# SSH al servidor de produccion:
ssh [email protected]

# El codigo esta en:
/home/chatwoot/chatwoot/

Deploy paso a paso

# 1. Subir archivos (desde local)
scp archivo [email protected]:/home/chatwoot/chatwoot/path/

# 2. Verificar sintaxis Ruby
cd /home/chatwoot/chatwoot
ruby -c app/controllers/path/file.rb

# 3. Build frontend (si cambiaron .vue/.js/.css)
sudo -u chatwoot bash -c 'cd /home/chatwoot/chatwoot && \
  CI=true RAILS_ENV=production \
  NODE_OPTIONS="--max-old-space-size=3072" \
  bundle exec rails assets:precompile'

# 4. Limpiar cache bootsnap (si cambiaron .rb)
rm -rf tmp/cache/bootsnap*

# 5. Reiniciar servicios
pkill -9 -f puma
sleep 2
systemctl restart chatwoot-puma
systemctl restart chatwoot-sidekiq

# 6. Purgar cache Cloudflare
curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/purge_cache" \
  -H "X-Auth-Email: EMAIL" \
  -H "X-Auth-Key: API_KEY" \
  -d '{"purge_everything":true}'

# 7. Verificar
systemctl status chatwoot-puma
curl -sk -o /dev/null -w "%{http_code}" https://app.fullchat.co/app/login

FullCall PBX

Arquitectura VoIP

FreePBX (207.180.234.156:8280)
  |-- Asterisk 17.9.3
  |-- PJSIP (18 endpoints: 100-109 internos, 200-207 GoIP)
  |-- WebSocket WSS (wss://call.fullchat.co/ws)
  |-- ARI REST API (:8188, user: fullcall)
  |
  |-- Trunk 1: GoIP Gateway (186.154.148.252:5060)
  |     |-- 31 SIMs GSM Colombia
  |     |-- SMS via HTTP API
  |
  |-- Trunk 2: Postal Asterisk (217.76.58.191:5070)
       |-- Asterisk 20.18.2
       |-- Kamailio SIP proxy

WebRTC Softphone (integrado en Dashboard)

# Componente: AsteriskSoftphone.vue
# Cargado en: Dashboard.vue (async)
# Libreria: JsSIP 3.10.1 (CDN)

# API endpoint para config:
GET /api/v1/accounts/:id/training/voice_config
Response: {
  ws_url: "wss://call.fullchat.co/ws",
  realm: "207.180.234.156",
  extension: "101",
  password: "FullCall101!",
  features: { recording: true, transfer: true }
}

# Click-to-Call event (desde ContactInfoRow.vue):
window.dispatchEvent(new CustomEvent('fullcall:dial', {
  detail: { number: '3001234567' }
}));

Sistema de Temas

// 27 temas disponibles en fullchatTheme.js
// Cada tema define 5 colores que generan 133 CSS variables

// Aplicar tema:
import { applyTheme } from 'dashboard/plugins/fullchatTheme';
applyTheme('emerald'); // o sky, navy, violet, rose, sunset, etc.

// CSS variables generadas:
var(--fc-primary)        // Color principal
var(--fc-success)        // Verde (teal)
var(--fc-warning)        // Amarillo
var(--fc-danger)         // Rojo
var(--fc-text)           // Texto principal
var(--fc-text-muted)     // Texto secundario
var(--fc-surface)        // Fondo
var(--fc-border)         // Bordes

// Clases Chatwoot nativas (siempre usar estas):
text-n-slate-12          // Texto principal
text-n-slate-11          // Texto secundario
text-n-blue-9            // Accent
text-n-teal-9            // Success
text-n-ruby-9            // Danger
bg-n-solid-2             // Superficie elevada
bg-n-background          // Fondo
border-n-weak            // Bordes suaves

Canales e Integraciones

Variables de Entorno Clave

# Core
FRONTEND_URL=https://app.fullchat.co
SECRET_KEY_BASE=...
RAILS_ENV=production

# Database
POSTGRES_HOST=localhost
POSTGRES_DATABASE=chatwoot_production
POSTGRES_USERNAME=chatwoot

# Redis
REDIS_URL=redis://127.0.0.1:6379/0

# Email (Postal)
SMTP_ADDRESS=mail.fullchat.co
SMTP_PORT=25
SMTP_USERNAME=fc/JMrL8Qbn...
MAILER_SENDER_EMAIL=FullChat <[email protected]>

# Puma
WEB_CONCURRENCY=4
RAILS_MAX_THREADS=5

Testing

# Backend (RSpec - 783 test files)
cd /home/chatwoot/chatwoot
RAILS_ENV=test bundle exec rspec

# Frontend (Vitest - 334 test files)
npm test            # Run once
npm run test:watch  # Watch mode
npm run test:coverage # Coverage report

Equipo y Contacto

Rol	Nombre	Email
CEO / CTO	Gabriel Rodriguez	[email protected]
Empresa	Teleya!	[email protected]
Producto	FullChat	app.fullchat.co

Capacidades Completas (233+)

Inventario exhaustivo de todas las funciones, modulos y beneficios de la plataforma. Cada capacidad es controlable desde el SaaS Super Admin V2: feature flags, plan guards, permisos RBAC, auditoria y tracking de uso.

1. Comunicacion Omnicanal (18 capacidades)

Mensajeria — 8 canales

#	Canal	Tecnologia	Tipo
1	WhatsApp Business	Evolution API (Baileys) + YCloud	Multi-instancia
2	Facebook Messenger	Graph API	Bidireccional
3	Instagram DM	Graph API	Bidireccional
4	TikTok	TikTok API	Bidireccional
5	Web Chat Widget	SDK embebible	Personalizable
6	Email	ActionMailbox + IMAP/SMTP	Inbound + Outbound
7	Telegram	Bot API	Bidireccional
8	SMS GSM	GoIP 32 canales	Costo cero Colombia

Voz y Telefonia — 7 capacidades

#	Capacidad	Detalle
9	Click-to-Call	Llamar desde conversacion, evento fullcall:dial
10	Auto-Conversacion	Llamada entrante crea contacto + conversacion
11	Grabacion → Conversacion	Audio se sube como attachment via webhook
12	WebRTC Softphone	JsSIP 3.10 integrado en dashboard
13	IVR Interactivo	Menus telefonicos multinivel
14	Colas de llamadas	Ring groups + estrategias
15	18 Extensiones PJSIP	100-109 agentes, 200-207 GoIP

Video — 3 capacidades

#	Capacidad	Detalle
16	Videollamadas Jitsi	Integrado en conversaciones
17	Grabacion de video	Opcional por plan
18	Compartir pantalla	Opcional por plan

2. CRM y Ventas — Pipeline (14)

#	Capacidad	Detalle
19	Tablero Kanban	Drag-drop entre etapas
20	Pipelines multiples	Ventas, soporte, custom
21	Etapas personalizables	Color, posicion, probabilidad, won/lost
22	Deals CRUD	Valor monetario, prioridad, producto
23	Probabilidad ponderada	Valor × probabilidad automatico
24	Historial actividades	Timeline por deal
25	Asignacion agente/equipo	Por deal individual
26	Link deal ↔ conversacion	Asociar contexto de chat
27	Exportar CSV	Deals con filtros
28	Estadisticas de ventas	Won, lost, avg, days to close
29	Empresas (Companies)	Gestion con contactos asociados
30	CRM Externo (Twenty)	REST + GraphQL bidireccional

3. Instalaciones / Field Service (19)

#	Capacidad	Detalle
31	CRUD instalaciones	Crear, editar, filtrar por zona/fecha/estado
32	Import masivo Excel	Parser inteligente, auto-detect header
33	Validacion WhatsApp	Verifica numero activo en WA
34	Deteccion carrier	Operador movil automatico
35	Geolocalizacion	Coordenadas + departamento + ciudad
36	Mapa estatico	OpenStreetMap + Pillow
37	Ciclo confirmacion WA	Mensaje + audio TTS + ubicacion nativa
38	Recordatorio automatico	Espera 3 min → reenvio
39	Escalacion SMS	No responde WA → SMS GoIP
40	Escalacion llamada	No responde SMS → llamada Asterisk
41	Clasificador NLP	CONFIRMO / CAMBIAR / NO PUEDO / ambiguo
42	Auto-respuesta	Responde segun clasificacion
43	Reagendamiento	Parse flexible de nueva fecha
44	Resumen admin	Notificacion final via WhatsApp
45	Timeline visual	Flujo tiempo real, refresh 10s
46	TTS	Audio colombiano (edge-tts)
47	23 columnas auditoria	wa_sent_at, carrier, audit_log JSONB
48	Vista calendario	Instalaciones por dia
49	Estadisticas	Por periodo, zona, instalador

4. Campanas Multicanal (8)

#	Capacidad	Detalle
50	Campanas WhatsApp	Templates masivos
51	Campanas SMS	GoIP 32 canales GSM
52	Campanas Email	Postal SMTP propio
53	Campanas Voz	Marcador automatico Asterisk
54	Segmentacion	Filtros por atributos
55	Programacion	Fecha/hora futuro
56	Marcador predictivo	Discado con ajuste velocidad
57	AMD	Deteccion contestador

5-12. Modulos Adicionales

Modulo	Capacidades	Highlight
Email Marketing (FullSend)	5	Templates, variables, tracking, Postal SMTP
Centro de Llamadas	6	Monitor real-time, CDR, hangup remoto
IVR Builder	6	Editor visual, guardar a FreePBX via SSH
Voice Bot IA	5	GPT-4.1 + Whisper + TTS 24/7
Automatizaciones (n8n)	9	Workflows, macros, SLA, auto-resolve
Referidos/Afiliados	9	Multinivel, comisiones, payouts
Training Center	6	Niveles, quizzes, certificados
Centro de Ayuda	5	Portales, embeddings IA, widget

13. Inteligencia Artificial — Captain (10)

#	Capacidad	Detalle
111	Captain AI v1/v2	Asistente de agente con tools
112	Captain Tasks	Tareas automatizadas por IA
113	Agent Bots	Bots personalizables por inbox
114	CSAT Review	Analisis IA de satisfaccion
115	AI Chat (Admin)	Chat con IA desde panel SaaS
116	AI Analyze/Execute	Analisis y acciones via IA
117	Multi-provider	OpenAI, Anthropic, Gemini, DeepSeek, Mistral, Perplexity

14. Contactos y Conversaciones (14)

#	Capacidad	Detalle
121	CRUD contactos	Import CSV, export, merge
122	Atributos custom	Definibles por cuenta
123	Labels + filtros	Tags + vistas guardadas
124	Busqueda avanzada	GIN + full text + pgVector
125	Respuestas enlatadas	Templates con atajos
126	Menciones + participantes	Colaboracion en conversaciones
127	Notas internas	Solo agentes
128	Typing + status	Real-time via ActionCable
129	Adjuntos multimedia	Imagenes, docs, audio, video

15. Gestion de Equipos (8)

#	Capacidad	Detalle
135	Teams + Agents CRUD	Agrupacion, roles, capacidad
136	Inboxes configurables	Por tipo de canal
137	Working hours	Horarios por inbox
138	Asignacion automatica	Round robin, capacity based
139	20 permisos granulares	Custom roles con 2^20 combinaciones
140	12 plantillas de rol	Predefinidas por funcion

16. SaaS Super Admin V2 — 157 acciones

Area	Acciones	Endpoints clave
Cuentas	11	CRUD, suspend, activate, impersonate, seed, export
Usuarios	6	Roles, password, logout, custom roles
Planes	8	CRUD, clone, 40+ campos por plan
Pagos	4	Register, revenue, export
Features	3	76 flags toggle global/por cuenta
App Config	2	17 secciones, 60+ variables
CRM/Pipeline	12	Deals, stages, activities CRUD
Training	10	Levels, questions, certificates CRUD
Afiliados	11	Affiliates, rules, commissions, payouts
Comunicaciones	6	GoIP, SMS, Voice, Extensions
Infraestructura	14	Health, Docker, DB, logs, storage, Cloudflare
IA	4	Chat, analyze, execute, models
Bots/Apps	6	Agent bots, platform apps CRUD
Monitoring	5	Sidekiq, uptime, diagnostics

17. Seguridad y Auditoria

20 Permisos RBAC enforced en 19 controllers

Grupo	Permisos
Conversaciones (4)	conversation_manage, conversation_unassigned_manage, conversation_participating_manage, conversation_monitor
Contactos (3)	contact_manage, contact_view_pii, crm_manage
Marketing (2)	campaign_manage, knowledge_base_manage
Operaciones (4)	team_manage, agent_manage, inbox_manage, automation_manage
Inteligencia (3)	report_manage, captain_manage, audit_view
Admin (4)	integration_manage, settings_manage, billing_manage, readonly_global

Auditoria: 13 controllers • Tracking: 12 contadores mensuales

# Auditoria automatica en:
conversation, contact, pipeline, campaign, team, agent, inbox,
automation_rule, deal, installation, referral, sms, module

# Tracking mensual por cuenta (SaasUsageRecord):
messages_count, conversations_count, sms_sent, emails_sent,
voice_minutes, video_minutes, whatsapp_messages, deals_created,
installations_processed, campaigns_sent, automations_executed, ai_requests

18. Gobernanza SaaS — 7 Capas por Modulo

Capa	Archivo	Funcion
1 Feature Flag	config/features.yml	Toggle on/off por cuenta
2 Route Guard	dashboard.routes.js	Bloquea navegacion frontend
3 Sidebar	Sidebar.vue	Oculta item segun plan
4 Plan Guard	before_action	403 si plan no incluye
5 Permisos	PermissionEnforcement	Solo roles autorizados
6 Auditoria	OperationalAudit	Log de quien/que/cuando
7 Tracking	SaasUsageRecord	Contadores mensuales

19. Integraciones Externas (20+)

Integracion	Uso	Acceso
Evolution API	WhatsApp multi-instancia	:8080
Postal SMTP	Email propio	mail.fullchat.co
Twenty CRM	CRM REST+GraphQL	:4000
n8n	Automatizacion visual	:5678
FreePBX/Asterisk	PBX completa	call.fullchat.co
GoIP Gateway	32 canales GSM	goip.fullchat.co
Jitsi Meet	Videoconferencia	meet.fullchat.co
OpenAI/Anthropic/Gemini	LLMs multiple	API cloud
Cloudflare	CDN + cache purge	API
Slack/Linear/Notion	Productividad	Webhooks/API
Shopify/Stripe	Commerce + Pagos	API
MinIO	Object storage	:9000

20. Temas y Personalizacion (5)

Capacidad	Detalle
27 temas visuales	Azules, verdes, morados, rojos, neutros, sectoriales
Variables CSS --fc-*	Gobiernan 100% de la UI
Dark mode	Automatico + manual
Branding	Logo, nombre, URL por cuenta
Disable branding	Plan Enterprise

Resumen Final