API de Notificações de Voz - Lovi AI Documentation

Introdução

Notificações de voz permitem que você faça chamadas automatizadas com agentes virtuais. Este endpoint permite enviar chamadas de voz com agentes alimentados por IA para seus contatos, proporcionando uma experiência de voz personalizada.

📞 Enviar Notificação de Voz

Para enviar uma notificação de voz via API da Lovi, faça uma requisição POST ao endpoint de voz com os parâmetros necessários e autenticação.

Método: POST Formato: JSON

Endpoint

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

Parâmetros de Query

Parâmetro	Obrigatório	Descrição
`access_key`	Sim	Sua chave de acesso única da API.
`unflatten`	Não	Se definido como `true`, o corpo deve conter variáveis planas (sem objetos aninhados). Se definido como `false` ou omitido, o corpo pode conter objetos aninhados.

URL de Exemplo:

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

Headers

Chave	Valor	Obrigatório	Descrição
Content-Type	application/json	Sim	Indica que o corpo da requisição está em formato JSON.

Nota: A autenticação é feita via parâmetro access_key na URL, não através de headers.

Corpo da Requisição

O corpo da requisição contém os detalhes da notificação de voz.

Estrutura com objetos aninhados (unflatten=false ou omitido)

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

Estrutura com variáveis 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 Obrigatórios

Parâmetro	Tipo	Descrição	Exemplo
`contact.number`	String	Número de telefone sem ’+’ ou espaços	`"34666033135"`
`recipient_id`	String	ID ou número de telefone do destinatário	`"34911670470"`
`agent_id`	String	Identificador único do agente de voz	`"uuid-agente-voz"`
`notification_type`	String	Tipo para análises	`"marketing"`, `"transactional"`
`campaign_name`	String	Nome identificador da campanha	`"Voice Campaign Q4"`

Parâmetros Opcionais

Parâmetro	Tipo	Descrição	Exemplo	Padrão
`contact.first_name`	String	Primeiro nome do contato	`"María"`	-
`contact.last_name`	String	Sobrenome do contato	`"González"`	-
`contact.email`	String	Email do contato	`"maria@email.com"`	-
`name_event`	String	Evento para disparar fluxos	`"info-curso-enfermeria"`	-
`datetime_sending`	DateTime	Data/hora agendada (ISO 8601)	`"2024-12-25T09:00:00"`	Imediato
`timezone`	String	Fuso horário para agendamento	`"Europe/Madrid"`	`"UTC"`

Campos Personalizados do Contato: Você pode incluir quaisquer campos adicionais no objeto contact para personalização (ex.: titulacion, fuente_cliente, etc.).

Resposta

Quando a requisição é bem-sucedida, a resposta conterá:

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

Recursos Específicos de Voz

Agentes com IA: Use agentes virtuais com síntese de voz natural
Personalização: Inclua dados personalizados do contato para chamadas personalizadas
Agendamento: Programe chamadas para horários específicos com suporte a fuso horário
Gatilhos de Eventos: Dispare fluxos de conversa específicos com name_event

Boas Práticas

Horário: Agende chamadas durante o horário comercial para melhor engajamento
Personalização: Inclua informações relevantes do contato para melhor fluxo de conversa
Seleção de Agente: Escolha agentes apropriados com base no caso de uso (vendas, suporte, etc.)
Conformidade: Garanta que as chamadas estejam em conformidade com regulamentações locais e requisitos de consentimento

📚 Dicas para Desenvolvimento de Voz

Sempre inclua agent_id para notificações de voz
Use recursos de agendamento para respeitar fusos horários
Teste com agentes de desenvolvimento antes da produção
Monitore taxas de conclusão de chamadas e ajuste o horário conforme necessário

​Introdução

​📞 Enviar Notificação de Voz

​Endpoint

​Parâmetros de Query

​Headers

​Corpo da Requisição

​Estrutura com objetos aninhados (unflatten=false ou omitido)

​Estrutura com variáveis planas (unflatten=true)

​Parâmetros Obrigatórios

​Parâmetros Opcionais

​Resposta

​Recursos Específicos de Voz

​Boas Práticas

​📚 Dicas para Desenvolvimento de Voz