API de Notificaciones de Voz - Lovi AI Documentation

Introducción

Las notificaciones de voz te permiten realizar llamadas automatizadas con agentes virtuales. Este endpoint te permite enviar llamadas de voz con agentes impulsados por IA a tus contactos, proporcionando una experiencia de voz personalizada.

📞 Enviar Notificación de Voz

Para enviar una notificación de voz a través de la API de Lovi, realiza una solicitud POST al endpoint de voz con los parámetros necesarios y la autenticación.

Método: POST Formato: JSON

Endpoint

POST https://cloud.lovi.ai/functions/v1/notify/voice?access_key={TU_ACCESS_KEY}

Parámetros de Consulta

Parámetro	Requerido	Descripción
`access_key`	Sí	Tu clave de acceso única a la API.
`unflatten`	No	Si se establece en `true`, el cuerpo debe contener variables planas (sin objetos anidados). Si se establece en `false` u omite, el cuerpo puede contener objetos anidados.

URL de Ejemplo:

POST https://cloud.lovi.ai/functions/v1/notify/voice?access_key=tu-api-key&unflatten=true

Encabezados

Clave	Valor	Requerido	Descripción
Content-Type	application/json	Sí	Indica que el cuerpo de la solicitud está en formato JSON.

Nota: La autenticación se gestiona a través del parámetro access_key en la URL, no a través de los encabezados.

Cuerpo de la Solicitud

Estructura con objetos anidados (unflatten=false o sin especificar)

{
  "contact": {
    "number": "34666033135",
    "first_name": "María",
    "last_name": "González",
    "email": "maria@email.com",
    "titulacion": "Técnico en Enfermería",
    "fuente_cliente": "Web Principal"
  },
  "recipient_id": "34911670470",
  "agent_id": "uuid-agente-voz",
  "notification_type": "marketing",
  "campaign_name": "Llamada Informativa Q4",
  "name_event": "info-curso-enfermeria",
  "datetime_sending": "2024-12-25T09:00:00",
  "timezone": "Europe/Madrid"
}

Estructura con variables planas (unflatten=true)

{
  "contact.number": "34666033135",
  "contact.first_name": "María",
  "contact.last_name": "González",
  "contact.email": "maria@email.com",
  "contact.titulacion": "Técnico en Enfermería",
  "contact.fuente_cliente": "Web Principal",
  "recipient_id": "34911670470",
  "agent_id": "uuid-agente-voz",
  "notification_type": "marketing",
  "campaign_name": "Llamada Informativa Q4",
  "name_event": "info-curso-enfermeria",
  "datetime_sending": "2024-12-25T09:00:00",
  "timezone": "Europe/Madrid"
}

Parámetros Requeridos

Parámetro	Tipo	Descripción	Ejemplo
`contact.number`	String	Número de teléfono sin ’+’ ni espacios	`"34666033135"`
`recipient_id`	String	ID o número de teléfono del destinatario	`"34911670470"`
`agent_id`	String	Identificador único del agente de voz	`"uuid-agente-voz"`
`notification_type`	String	Tipo para analíticas	`"marketing"`, `"transactional"`
`campaign_name`	String	Nombre identificador de la campaña	`"Campaña de Voz Q4"`

Parámetros Opcionales

Parámetro	Tipo	Descripción	Ejemplo	Predeterminado
`contact.first_name`	String	Nombre del contacto	`"María"`	-
`contact.last_name`	String	Apellido del contacto	`"González"`	-
`contact.email`	String	Email del contacto	`"maria@email.com"`	-
`name_event`	String	Evento para activar flujos	`"info-curso-enfermeria"`	-
`datetime_sending`	DateTime	Fecha/hora programada (ISO 8601)	`"2024-12-25T09:00:00"`	Inmediato
`timezone`	String	Zona horaria para la programación	`"Europe/Madrid"`	`"UTC"`

Campos de Contacto Personalizados: Puedes incluir cualquier campo adicional en el objeto contact para personalización (ej. titulacion, fuente_cliente, etc.).

Respuesta

Cuando la solicitud es exitosa, la respuesta contendrá:

{
  "success": true,
  "message": "Notificación de voz puesta en cola correctamente",
  "notification_id": "uuid-notificacion",
  "scheduled_time": "2024-12-25T09:00:00Z"
}

Características Específicas de Voz

Agentes Impulsados por IA: Usa agentes virtuales con síntesis de voz natural
Personalización: Incluye datos de contacto personalizados para llamadas personalizadas
Programación: Programa llamadas para momentos específicos con soporte de zona horaria
Activadores de Eventos: Activa flujos de conversación específicos con name_event

Mejores Prácticas

Horario: Programa las llamadas durante el horario comercial para mayor participación
Personalización: Incluye información relevante del contacto para un mejor flujo de conversación
Selección de Agente: Elige agentes apropiados según el caso de uso (ventas, soporte, etc.)
Cumplimiento: Asegúrate de que las llamadas cumplan con las regulaciones locales y los requisitos de consentimiento

📚 Consejos para el Desarrollo de Voz

Siempre incluye agent_id para las notificaciones de voz
Usa las funciones de programación para respetar las zonas horarias
Prueba con agentes de desarrollo antes de producción
Monitoriza las tasas de finalización de llamadas y ajusta el horario en consecuencia

​Introducción

​📞 Enviar Notificación de Voz

​Endpoint

​Parámetros de Consulta

​Encabezados

​Cuerpo de la Solicitud

​Estructura con objetos anidados (unflatten=false o sin especificar)

​Estructura con variables planas (unflatten=true)

​Parámetros Requeridos

​Parámetros Opcionales

​Respuesta

​Características Específicas de Voz

​Mejores Prácticas

​📚 Consejos para el Desarrollo de Voz