← Documentación interna

Voice v2 — La voz de tu empresa, en cualquier canal

Reposicionamos voice.cadences.app: deja de ser "asistente telefónico" y pasa a ser la voz unificada de la marca — teléfono, WhatsApp, email y chat web — con la misma personalidad, la misma memoria y las mismas conexiones a Shopify, calendario y transportistas.

1. Por qué seguimos llamándolo Voice

"Voice" no se refiere al canal telefónico, sino a la voz de marca: el tono, la personalidad y el conocimiento que cualquier negocio tiene cuando atiende a un cliente. Esa voz hoy se reparte entre quien coge el teléfono, quien contesta el email y quien gestiona el WhatsApp — y nunca es la misma. Cadences Voice unifica esa voz en un único asistente.

Ventajas de mantener el nombre:

• Dominio voice.cadences.app ya posicionado y comprado.
• Toda la base de datos (voice_*) y endpoints (/api/voice/*) se reutilizan sin migración masiva.
• Comercialmente "voz" es más evocador y diferenciador que "agentes" o "inbox" (mercado saturado).
• El canal voz sigue siendo el más complejo y el que justifica el ticket alto.

2. Concepto de producto

Un asistente Voice se define una vez y se "encarna" en cada canal:

Asistente "Recepción Vila Sen Vento"
├── Personalidad (system prompt + tono)
├── Voz clonada (ElevenLabs PVC) — solo canal teléfono
├── Knowledge base (productos, alérgenos, FAQs, políticas)
├── Tools / conectores (Shopify, SEUR, Calendar...)
├── Memoria cross-canal (voice_customer_facts)
└── Workflows post-interacción

Canales activos:
 ☎  +34 988 ...   (teléfono Twilio)
 💬  +34 600 ...   (WhatsApp Cloud API)
 ✉  [email protected]  (Gmail/IMAP — modo borrador)
 🌐  widget en vilasenvento.com  (web chat)

3. Arquitectura técnica

3.1 Capas

3.2 Migration nueva propuesta

migrations/0157_voice_channels_and_inbox.sql

-- canales por organización (más allá de voz)
CREATE TABLE voice_channels (
  id TEXT PRIMARY KEY,
  organizationId TEXT NOT NULL,
  assistantId TEXT NOT NULL,
  type TEXT NOT NULL,             -- voice | whatsapp | email | webchat | sms
  identifier TEXT NOT NULL,       -- número, email, slug widget
  config TEXT,                    -- JSON específico del canal
  status TEXT DEFAULT 'active',
  createdAt INTEGER NOT NULL,
  UNIQUE (type, identifier)
);

-- conversaciones unificadas (el hilo del cliente, sea cual sea el canal)
CREATE TABLE voice_conversations (
  id TEXT PRIMARY KEY,
  organizationId TEXT NOT NULL,
  contactId TEXT,
  channelId TEXT NOT NULL,
  assistantId TEXT NOT NULL,
  subject TEXT,
  status TEXT DEFAULT 'open',     -- open | snoozed | closed | escalated
  intent TEXT,
  sentiment REAL,
  summary TEXT,
  assignedTo TEXT,                -- user humano si está escalada
  lastMessageAt INTEGER,
  createdAt INTEGER NOT NULL
);

-- mensajes (mezcla turnos voz transcritos, mensajes whatsapp, emails...)
CREATE TABLE voice_messages (
  id TEXT PRIMARY KEY,
  conversationId TEXT NOT NULL,
  direction TEXT NOT NULL,        -- in | out
  role TEXT NOT NULL,             -- user | assistant | human | system
  body TEXT,
  attachments TEXT,               -- JSON array
  providerMsgId TEXT,
  ts INTEGER NOT NULL
);

-- borradores pendientes de aprobación humana (email, sobre todo)
CREATE TABLE voice_drafts (
  id TEXT PRIMARY KEY,
  conversationId TEXT NOT NULL,
  body TEXT NOT NULL,
  confidence REAL,
  requiresApproval INTEGER DEFAULT 1,
  approvedBy TEXT,
  approvedAt INTEGER,
  sentAt INTEGER,
  createdAt INTEGER NOT NULL
);

-- enlazar voice_calls a su conversación (no rompe nada existente)
ALTER TABLE voice_calls ADD COLUMN conversationId TEXT;

3.3 Endpoints nuevos

GET    /api/voice/channels
POST   /api/voice/channels                       (crear canal whatsapp/email/webchat)
PATCH  /api/voice/channels/:id
DELETE /api/voice/channels/:id

GET    /api/voice/conversations?status=&channel=&q=
GET    /api/voice/conversations/:id              (incluye messages + contact + facts)
PATCH  /api/voice/conversations/:id              (status, assignedTo)
POST   /api/voice/conversations/:id/messages     (humano envía manualmente)

POST   /api/voice/drafts/:id/approve
POST   /api/voice/drafts/:id/reject
PATCH  /api/voice/drafts/:id                     (editar antes de aprobar)

# Webhooks entrantes (uno por canal)
POST   /api/voice/inbound/whatsapp               (Meta Cloud API)
POST   /api/voice/inbound/email                  (IMAP poller o SES/Mailgun inbound)
POST   /api/voice/inbound/webchat                (WS o REST desde widget)

4. Memoria cross-canal

La promesa estrella de la reunión: "que la IA sepa que ya he llamado, que mi hija es celíaca, que prefiero contrareembolso". Hoy ya existe la tabla voice_customer_facts alimentada por el analizador de llamadas. El cambio es:

• Cualquier canal escribe facts, no solo voz.
• El system prompt del LLM siempre incluye los facts del contacto antes de generar respuesta.
• Política de extracción explícita: alergias, preferencias de pago, eventos personales, productos favoritos, puntos de venta, horario preferido.
• UI en /admin/contacts/:id permite editar/eliminar facts (RGPD: derecho de rectificación).

5. Conectores y orden de implementación

6. Inbox unificado

Pantalla nueva /admin/inbox estilo Front / Missive:

7. Workflows v2

El motor actual ya soporta steps whatsapp | sms | email | crm | calendar | notify_team. Añadimos triggers de canal y de Shopify:

• email_received / whatsapp_received / webchat_started
• shopify_order_created / shopify_order_paid / shopify_order_fulfilled
• shipment_delayed (tracking sin movimiento >48h)
• cod_order_unconfirmed (contrareembolso sin confirmar >6h) — caso real Vila Sen Vento
• vip_detected (cliente con >N pedidos o ticket alto)

Plantillas nuevas a crear:

• cod-confirma-pedido: WhatsApp automático tras pedido contrareembolso pidiendo confirmación.
• checkout-atascado: si se inicia checkout y no se completa en 30 min, llama el asistente o manda WA.
• tracking-retraso: si SEUR no mueve el envío en 48h, email proactivo + crear ticket.
• cliente-recurrente-evento: detectar palabras "boda", "cumpleaños", "comunión" → crear lead en CRM con etiqueta "evento especial".

8. Empaquetado comercial

Consumo (pass-through con markup x1.3)

• Voz: minutos Twilio + minutos ElevenLabs Conversational
• WhatsApp: por conversación facturable Meta (24h)
• IA: tokens input/output Gemini Flash / DeepSeek según asistente
• Almacenamiento R2: incluido hasta 10 GB / asistente

Visible en /admin/billing con desglose mensual transparente.

9. Roadmap de ejecución

1. Migration 0157 (channels + conversations + messages + drafts) y endpoints CRUD básicos.
2. Conector Shopify read-only de pedidos/productos + tool lookup_order y lookup_product ya disponible para voz hoy.
3. Memoria cross-canal: extracción unificada de facts, inyección en system prompt.
4. WhatsApp Cloud API + UI inbox v0 (solo voz + WA, para validar el modelo).
5. Email IMAP/Gmail OAuth con borradores aprobables.
6. Web chat widget embebible (JS estático + WS al mismo Worker).
7. Tracking transportistas (lookup_shipment) + workflow shipment_delayed.
8. Página pública de voice.cadences.app reescrita con narrativa multi-canal + 3 planes.
9. Billing real con consumo medido por canal.
10. Voz clonada PVC (ya soportado técnicamente, falta proceso comercial + consentimiento RGPD).

10. Riesgos & cumplimiento

Documento interno · 2026-04-28 · Voice v2 vision