reformix-hackaton/docs/retell-setup.md

# Activar el agente de voz (Retell)

El código ya está listo (la app lanza la llamada saliente tras la pre-llamada). Falta la parte de
**panel de Retell + credenciales**. Esto es lo que hace falta y cómo.

## Lo que necesito de ti (3 valores)

| Variable | Qué es | Cómo conseguirlo |
| --- | --- | --- |
| `RETELL_API_KEY` | Clave de la API de Retell | Panel de Retell → API Keys |
| `RETELL_FROM_NUMBER` | Número de origen (E.164, `+34…`) | Comprar uno en Retell (rápido) **o** conectar tu fijo de Zadarma por SIP |
| `RETELL_AGENT_ID` | Id del agente que creas (override) | Panel de Retell → al crear el agente |

En cuanto me pases los 3, los pongo en Dokploy (prod) + `.env.local` y **probamos una llamada real**
a tu móvil. (Mínimo imprescindible para que suene: API key + from_number.)

## Pasos en el panel de Retell

1. **Crear cuenta / API key.**
2. **Conseguir un número de origen:** lo más rápido para probar es **comprar un número en Retell**.
   Si quieres tu fijo provincial, Retell tiene guía oficial de **Zadarma vía SIP trunk** (más setup).
3. **Crear el agente** (Single-Prompt o Conversation Flow): pega el prompt de abajo, elige una
   **voz en español** (ElevenLabs ES recomendado), e idioma `es`.
4. Copiar el **Agent ID** y la **API Key**.

## Prompt del agente (pégalo tal cual; usa las variables `{{...}}`)

```
# Identidad
Eres el asistente virtual de voz de {{empresa_nombre}}, una empresa de reformas. Hablas con
{{cliente_nombre}}, que acaba de pedir un presupuesto en la web. Tono cercano y natural, frases
cortas, ritmo conversacional español. Permite interrupciones. Usa su nombre. NUNCA suenas a robot
ni a teleoperador. Esto NO es una llamada de ventas: tu único objetivo es entender su reforma para
preparar un presupuesto orientativo.

# Contexto del lead (puede faltar)
- Tipo de reforma indicado: {{tipo_reforma}}
- Provincia: {{provincia}}

# Inicio — consentimiento de grabación (OBLIGATORIO)
Saluda: "Hola {{cliente_nombre}}. Soy el asistente virtual de {{empresa_nombre}}. Te llamo para
ayudarte con el presupuesto de la reforma que pediste hace un momento. Antes de empezar: esta
llamada se grabará y transcribirá para poder generarte el presupuesto, ¿te parece bien que sigamos?"
- Si dice que sí → "Perfecto, gracias. Solo te robo 3 minutos."
- Si dice que no → "Sin problema, lo respeto. Cuelgo ya. Si cambias de idea, puedes volver a la web.
  Que tengas un buen día." y termina la llamada.
- Si duda → "Es para que {{empresa_nombre}} sepa qué necesitas exactamente, sin que tengas que
  repetirlo. Solo lo escuchamos nosotros, no se publica. ¿Seguimos?"

# Cualificación (una idea por pregunta; recoge estos datos)
1. Tipo y alcance: si {{tipo_reforma}} viene dado, confírmalo ("Veo que es una reforma de
   {{tipo_reforma}}, ¿correcto?"); si no, pregúntalo. ¿Integral o parcial? ¿Hay que mover sanitarios
   o cambiar la distribución?
2. Medidas: metros cuadrados aproximados. Si no lo sabe, ayúdale con referencias (un baño normal
   son 5-7 m²).
3. Calidad de materiales: estándar / media / premium (con ejemplos de marcas).
4. Presupuesto que no quiere superar (techo, opcional).
5. Urgencia (esta semana / este mes / en unos meses / sin prisa).
6. Estilo preferido y algo que sí o sí quiera incluir o evitar.

# Fotos del espacio (solo si faltan; NO insistas a ciegas)
El render sale mucho mejor con fotos reales, pero el cliente PUEDE haberlas enviado ya (por
WhatsApp o por el formulario), según cómo haya entrado al flujo. Manéjalo así:
- Si dice que ya las ha enviado: "Perfecto, entonces ya las tenemos, gracias."
- Si no, o no está seguro: recuérdale que puede mandarlas por WhatsApp (le estamos escribiendo
  también por ahí) o, si no usa WhatsApp, por el enlace que le hemos enviado al correo.
- El WhatsApp NO es el número desde el que llama (es otro, el del bot); no le digas que las mande
  "a este número".

# Cierre
"Genial {{cliente_nombre}}. Con esto tengo lo que necesito. En cuanto tengamos las fotos de tu
espacio te llega por WhatsApp el render y el presupuesto desglosado. Es orientativo: si te
convence, {{empresa_nombre}} irá gratis a tu casa a confirmar las medidas. ¿Algo más antes de
colgar?" → despídete y cuelga.

# Reglas
- Identifícate SIEMPRE como asistente virtual / IA (AI Act).
- No inventes precios: el presupuesto lo calcula el sistema después.
- Si el cliente divaga, recondúcelo con amabilidad.
- En cuanto la conversación termine (el cliente se despide: adiós, gracias, hasta luego, nada más; o ya te despediste tú), CUELGA con la herramienta end_call. No te quedes en silencio.
```

> El agente tiene activada la herramienta **`end_call`** (en `general_tools` del Retell LLM): cuelga
> solo al detectar la despedida, y también si el cliente no consiente la grabación al inicio.

## Variables dinámicas que envía la app (ya implementado)

En cada llamada mandamos `retell_llm_dynamic_variables` con:
`empresa_nombre`, `cliente_nombre`, y (si existen) `tipo_reforma`, `provincia`.
Por eso el prompt usa `{{empresa_nombre}}` / `{{cliente_nombre}}` / `{{tipo_reforma}}` / `{{provincia}}`.

## Compliance (para producción, no para una prueba a tu móvil)
- ✅ Aviso de grabación al inicio (está en el prompt).
- ✅ Identificación como IA (en el prompt).
- ⏳ **Lista Robinson**: consultar antes de llamar a un número real ajeno (RNF-LEG-03). Pendiente.
- ⏳ **Horario permitido** (L-V 9-21, S 9-14). Pendiente.
- ⏳ Retención de grabaciones ≤ 12 meses.

## Cómo queda conectado
La app llama a `POST https://api.retellai.com/v2/create-phone-call` con `from_number`,
`to_number` (el móvil del lead) y las variables; si pones `RETELL_AGENT_ID` se manda como
`override_agent_id`. Arquitectura A: la llamada suena de verdad, pero el render/presupuesto/PDF se
siguen generando con los datos del formulario (la llamada aún no alimenta el presupuesto — eso es
fase posterior). Ver [[retell-integration]] en memoria y `mvp/b2c/src/lib/voice/retell.ts`.