Skip to main content

​
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

ParameterRequiredDescription
access_keyYesYour unique API access key.
unflattenNoIf 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

KeyValueRequiredDescription
Content-Typeapplication/jsonYesIndicates 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": "[email protected]",
    "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": "[email protected]",
  "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

ParameterTypeDescriptionExample
contact.numberStringPhone number without ’+’ or spaces"34666033135"
recipient_idStringID or phone number of the recipient"34911670470"
agent_idStringUnique identifier of the voice agent"uuid-agente-voz"
notification_typeStringType for analytics"marketing", "transactional"
campaign_nameStringCampaign identifier name"Voice Campaign Q4"

​
Optional Parameters

ParameterTypeDescriptionExampleDefault
contact.first_nameStringContact’s first name"María"-
contact.last_nameStringContact’s last name"González"-
contact.emailStringContact’s email"[email protected]"-
name_eventStringEvent to trigger flows"info-curso-enfermeria"-
datetime_sendingDateTimeScheduled date/time (ISO 8601)"2024-12-25T09:00:00"Immediate
timezoneStringTimezone 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