Voice Notifications API - Lovi AI Documentation

Introduction

Voice notifications allow you to make automated calls with virtual agents. This endpoint enables you to send voice calls with AI-powered agents to your contacts, providing a personalized voice experience.

📞 Send Voice Notification

To send a voice notification via the Lovi API, make a POST request to the voice endpoint with the necessary parameters and authentication.

Method: POST Format: JSON

Endpoint

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

Query Parameters

Parameter	Required	Description
`access_key`	Yes	Your unique API access key.
`unflatten`	No	If set to `true`, the body must contain flat variables (no nested objects). If set to `false` or omitted, the body can contain nested objects.

Example URL:

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

Headers

Key	Value	Required	Description
Content-Type	application/json	Yes	Indicates that the request body is in JSON format.

Note: Authentication is handled via the access_key parameter in the URL, not through headers.

Body Request

The body of the request contains the voice notification details.

Structure with nested objects (unflatten=false or omitted)

{
  "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"
}

Structure with flat variables (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"
}

Required Parameters

Parameter	Type	Description	Example
`contact.number`	String	Phone number without ’+’ or spaces	`"34666033135"`
`recipient_id`	String	ID or phone number of the recipient	`"34911670470"`
`agent_id`	String	Unique identifier of the voice agent	`"uuid-agente-voz"`
`notification_type`	String	Type for analytics	`"marketing"`, `"transactional"`
`campaign_name`	String	Campaign identifier name	`"Voice Campaign Q4"`

Optional Parameters

Parameter	Type	Description	Example	Default
`contact.first_name`	String	Contact’s first name	`"María"`	-
`contact.last_name`	String	Contact’s last name	`"González"`	-
`contact.email`	String	Contact’s email	`"maria@email.com"`	-
`name_event`	String	Event to trigger flows	`"info-curso-enfermeria"`	-
`datetime_sending`	DateTime	Scheduled date/time (ISO 8601)	`"2024-12-25T09:00:00"`	Immediate
`timezone`	String	Timezone for scheduling	`"Europe/Madrid"`	`"UTC"`

Custom Contact Fields: You can include any additional fields in the contact object for personalization (e.g., titulacion, fuente_cliente, etc.).

Response

When the request is successful, the response will contain:

{
  "success": true,
  "message": "Voice notification queued successfully",
  "notification_id": "uuid-notification",
  "scheduled_time": "2024-12-25T09:00:00Z"
}

Voice-Specific Features

AI-Powered Agents: Use virtual agents with natural voice synthesis
Personalization: Include custom contact data for personalized calls
Scheduling: Program calls for specific times with timezone support
Event Triggers: Trigger specific conversation flows with name_event

Best Practices

Timing: Schedule calls during business hours for better engagement
Personalization: Include relevant contact information for better conversation flow
Agent Selection: Choose appropriate agents based on use case (sales, support, etc.)
Compliance: Ensure calls comply with local regulations and consent requirements

📚 Tips for Voice Development

Always include agent_id for voice notifications
Use scheduling features to respect time zones
Test with development agents before production
Monitor call completion rates and adjust timing accordingly

​Introduction

​📞 Send Voice Notification

​Endpoint

​Query Parameters

​Headers

​Body Request

​Structure with nested objects (unflatten=false or omitted)

​Structure with flat variables (unflatten=true)

​Required Parameters

​Optional Parameters

​Response

​Voice-Specific Features

​Best Practices

​📚 Tips for Voice Development