Saltar a contenido

Twilio + Vapi (voz)

Marina no habla con Twilio directamente: la telefonía va a Vapi, que ejecuta el agente de voz y, al terminar la llamada, envía a Marina un webhook con la transcripción. Marina la clasifica y crea el lead.

Cliente ──▶ nº Twilio ──▶ Vapi (asistente + Marina) ──▶ webhook fin-de-llamada ──▶ api.marinacx.mywire.org

Requisitos

  • Una cuenta de Vapi (una por grupo/cuenta) con su API key.
  • Una cuenta de Twilio con un número (para pruebas vale un número de desarrollo).
  • El backend accesible por HTTPS: https://api.marinacx.mywire.org.

1. Crear el asistente en Vapi

  1. En Vapi, crea un asistente por concesionario (manual, no automático).
  2. Copia su Assistant ID.
  3. En Marina → concesionario → Configuración → Telefonía, pega el Assistant ID.
  4. En El agente, escribe el saludo y el guion, guarda y pulsa Enviar a Vapi (o usa Importar si ya lo configuraste en Vapi y quieres traerlo).

2. Apuntar el webhook de fin de llamada a Marina

En Vapi, configura el Server URL del asistente (o de la cuenta) a:

https://api.marinacx.mywire.org/webhooks/voice/vapi

Marina solo procesa los mensajes de tipo end-of-call-report; el resto los ignora.

Autenticación del webhook

El webhook es público, así que se protege con un secreto compartido (el Server URL Secret de Vapi):

  • Define en el backend la variable de entorno VAPI_WEBHOOK_SECRET con un valor fuerte.
  • En Vapi, configura ese mismo valor como cabecera x-vapi-secret en las llamadas al Server URL.

Si el secreto no coincide, Marina responde 401 y no procesa nada. Si no está configurado en el backend, el webhook devuelve 503.

Identificar el concesionario

Marina necesita saber a qué concesionario pertenece la llamada. Lo toma, por orden:

  1. dealership_id en la metadata de la llamada (call.metadata.dealership_id), o
  2. una cabecera fija x-dealership-id con el UUID del concesionario (útil en llamadas entrantes, que a menudo no llevan metadata).

Prueba con un número de desarrollo

Para una prueba rápida: en el asistente de Vapi añade la cabecera x-dealership-id con el UUID del concesionario y x-vapi-secret con tu secreto. Conecta el número de Twilio al asistente en Vapi, llama al número, cuelga, y comprueba que aparece el lead en el Panel del concesionario. Si algo falla, mira las trazas en /api/logger (ver abajo).

3. Conectar Twilio a Vapi

En Vapi, importa/conecta tu número de Twilio (Phone Numbers) y asígnalo al asistente del concesionario. La llamada entrante al número la atiende Marina.

Diagnóstico

  • Swagger: https://api.marinacx.mywire.org/docs para ver el contrato de /webhooks/voice/vapi.
  • Visor de trazas: https://api.marinacx.mywire.org/api/logger con la cabecera x-access-token: <LOGGER_ACCESS_TOKEN> (o ?access=<token>). Muestra las últimas trazas; nunca expone PII.
  • Un lead de voz aparece con origen: Llamada. Si el cliente dictó su nombre/teléfono, Marina los rellena; si no, el lead sale como Sin nombre.

Variables de entorno relevantes

Variable Para qué
VAPI_WEBHOOK_SECRET Verifica el webhook de Vapi (cabecera x-vapi-secret).
CLAUDE_API_KEY Clasificación de la transcripción.
LOGGER_ACCESS_TOKEN Acceso al visor de trazas /api/logger.
TURNSTILE_SITE_KEY / TURNSTILE_SECRET Captcha del formulario web (déjalas vacías para desactivarlo en dev).