Skip to main content

​
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ámetroRequeridoDescripción
access_keySíTu clave de acceso única a la API.
unflattenNoSi 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

ClaveValorRequeridoDescripción
Content-Typeapplication/jsonSí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ámetroTipoDescripciónEjemplo
contact.numberStringNúmero de teléfono sin ’+’ ni espacios"34666033135"
recipient_idStringID o número de teléfono del destinatario"34911670470"
agent_idStringIdentificador único del agente de voz"uuid-agente-voz"
notification_typeStringTipo para analíticas"marketing", "transactional"
campaign_nameStringNombre identificador de la campaña"Campaña de Voz Q4"

​
Parámetros Opcionales

ParámetroTipoDescripciónEjemploPredeterminado
contact.first_nameStringNombre del contacto"María"-
contact.last_nameStringApellido del contacto"González"-
contact.emailStringEmail del contacto"maria@email.com"-
name_eventStringEvento para activar flujos"info-curso-enfermeria"-
datetime_sendingDateTimeFecha/hora programada (ISO 8601)"2024-12-25T09:00:00"Inmediato
timezoneStringZona 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