> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API de Notificações de Voz

> Documentação oficial para uso da API de Voz da Lovi para enviar chamadas de voz automatizadas

## 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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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á:

```json theme={null}
{
  "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