> ## 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 WhatsApp > Documentação oficial para uso da API da Lovi com WhatsApp via Postman ## Introdução Esta seção fornece a documentação oficial para uso da API da Lovi com WhatsApp via Postman. Inclui instruções detalhadas sobre como configurar e testar requisições de API para integração com WhatsApp, garantindo comunicação fluida através da plataforma. A autenticação é realizada usando tokens que habilitam autenticação básica para os serviços da API. Para mais detalhes sobre como se autenticar, consulte a página de [Autenticação](./authentication). A API da Lovi suporta notificações WhatsApp com conteúdo multimídia, placeholders dinâmicos, entrega agendada e integração com fluxos de conversa. ### Recursos Principais: * Notificações WhatsApp com suporte a multimídia * Personalização de conteúdo dinâmico com placeholders * Entrega de mensagens agendadas com suporte a fuso horário * Integração com fluxos de conversa * Dois formatos de estrutura de dados (aninhado e plano) *** ## 📣 Enviar Notificação WhatsApp Para enviar uma notificação via API da Lovi, faça uma requisição POST ao endpoint com os parâmetros necessários e autenticação. > **Método**: POST **Formato**: JSON ### Endpoint ``` POST https://cloud.lovi.ai/functions/v1/notify?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. | **URLs de Exemplo:** ``` POST https://cloud.lovi.ai/functions/v1/notify?access_key=your-api-key POST https://cloud.lovi.ai/functions/v1/notify?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. *** ## 📋 Parâmetros da Requisição A API suporta dois formatos de estrutura de dados controlados pelo parâmetro `unflatten`. ### Parâmetros Obrigatórios | Parâmetro | Tipo | Descrição | Exemplo | | ----------------------- | --------------- | ----------------------------------------------------------------------------- | --------------------------------------------- | | `contact` OU `contacts` | Object OU Array | **Escolha um**: Contato único (objeto) OU Múltiplos contatos (array, máx 100) | Veja abaixo | | `language_template` | String | Código de idioma do template | `"es_ES"`, `"en_US"` | | `name_template` | String | Nome do template aprovado | `"welcome_user"` | | `recipient_id` | String | ID ou número de telefone do destinatário | `"34666033135"` | | `notification_type` | String | Tipo para análises | `"marketing"`, `"transactional"`, `"utility"` | | `campaign_name` | String | Nome identificador da campanha | `"Black Friday 2024"` | **Importante**: Você deve usar `contact` (para destinatário único) OU `contacts` (para múltiplos destinatários), mas NÃO ambos. ### Parâmetros Opcionais | Parâmetro | Tipo | Descrição | Quando Usar | Exemplo | | ------------------- | -------- | -------------------------------------- | ----------------------------------------------------- | ------------------------- | | `contact.name` | String | Nome do contato para personalização | Para mensagens personalizadas | `"Juan Pérez"` | | `contact.email` | String | Email do contato | Para dados adicionais de contato | `"juan@email.com"` | | `name_event` | String | Evento para disparar fluxos | Quando quiser iniciar um fluxo de conversa específico | `"intent-general-push"` | | `datetime_sending` | DateTime | Horário de entrega agendado (ISO 8601) | Quando quiser agendar a mensagem para depois | `"2024-12-25T10:30:00"` | | `timezone` | String | Fuso horário para entrega agendada | Quando usar `datetime_sending` | `"Europe/Madrid"` | | `components_push.*` | Mixed | Componentes do template (texto, mídia) | Quando o template requer conteúdo dinâmico | Veja seção de componentes | *** ## 👥 Destinatário Único vs Múltiplos ### Usando `contact` - Enviar para Uma Pessoa Use `contact` quando quiser enviar uma notificação para **um destinatário**. **Estrutura**: ```json theme={null} { "contact": { "number": "34666033135", "name": "John", "email": "john@example.com" } } ``` * `contact` é um **objeto** (não uma lista) * Campo obrigatório: `number` * Campos opcionais: `name`, `email` e quaisquer campos personalizados *** ### Usando `contacts` - Enviar para Múltiplas Pessoas (Envio em Massa) Use `contacts` quando quiser enviar a mesma notificação para **múltiplos destinatários** de uma vez. **Estrutura**: ```json theme={null} { "contacts": [ { "number": "34666033135", "name": "John" }, { "number": "34777044246", "name": "Sarah" }, { "number": "34888055357", "name": "Michael" } ] } ``` * `contacts` é uma **lista/array** (não um objeto único) * **Máximo**: 100 contatos por requisição * Cada contato na lista deve ter um `number` * Campos opcionais: `name`, `email` e quaisquer campos personalizados **Restrições Importantes**: * ⚠️ **Não é possível usar `unflatten=true` com `contacts`** - Envio em massa só funciona com estrutura aninhada * ⚠️ **Não é possível usar `contact` e `contacts`** na mesma requisição - escolha um * ⚠️ **A lista `contacts` não pode estar vazia** - deve ter pelo menos 1 contato *** ## 🔄 Formatos de Estrutura de Dados A API suporta dois formatos baseados no parâmetro `unflatten`: ### Estrutura Aninhada (unflatten=false ou omitido) Quando `unflatten=false` ou não especificado, use objetos aninhados: ```json theme={null} { "contact": { "number": "34666033135", "name": "Juan Pérez", "email": "juan@email.com" }, "components_push": { "header_text_0": "Welcome Message", "body_text_0": "Hello {{name}}", "body_text_1": "Your order is ready!", "footer_text_0": "Support Team" }, "language_template": "es_ES", "name_template": "order_ready", "recipient_id": "34666033135", "notification_type": "transactional", "campaign_name": "Order Notifications" } ``` ### Estrutura Plana (unflatten=true) Quando `unflatten=true`, todos os objetos aninhados devem ser achatados usando notação de ponto: ```json theme={null} { "contact.number": "34666033135", "contact.name": "Juan Pérez", "contact.email": "juan@email.com", "components_push.header_text_0": "Welcome Message", "components_push.body_text_0": "Hello {{name}}", "components_push.body_text_1": "Your order is ready!", "components_push.footer_text_0": "Support Team", "language_template": "es_ES", "name_template": "order_ready", "recipient_id": "34666033135", "notification_type": "transactional", "campaign_name": "Order Notifications" } ``` ### Quando Usar Cada Formato * **Estrutura Aninhada (`unflatten=false`)**: Recomendada para melhor legibilidade e quando seu sistema suporta objetos aninhados * **Estrutura Plana (`unflatten=true`)**: Use quando seu sistema não suporta objetos aninhados ou requer estrutura de dados plana *** ## 🎨 Componentes e Multimídia **IMPORTANTE**: Componentes que você pode enviar dinamicamente são **APENAS aqueles retornados pelo endpoint de componentes do template**. A estrutura varia dependendo se o template tem variáveis ou mídia. ### Regras de Nomenclatura de Componentes * **Header de mídia**: `header_image`, `header_video`, `header_document` (SEM número de sufixo) * **Variáveis do body**: `body_text_0`, `body_text_1`, `body_text_2`, etc. (com número de índice para cada placeholder `{"{1}"}`, `{"{2}"}`, `{"{3}"}`) * **Footer e Botões**: São ESTÁTICOS na definição do template e NÃO PODEM ser enviados dinamicamente ### Como Saber Quais Componentes Enviar 1. Primeiro, chame o endpoint de componentes do template: ``` GET /notify/template/components?access_key={key}&template={template_id} ``` 2. A API retorna apenas os componentes que você precisa fornecer: ```json theme={null} { "status": "OK", "components": ["header_image", "body_text_0", "body_text_1"] } ``` 3. Envie APENAS esses componentes na sua requisição de notificação ### Tipos de Componentes por Posição #### Componentes de Header (Apenas Mídia) **IMPORTANTE**: Apenas UM componente de header por template. O texto do header é ESTÁTICO no template. | Tipo | Nome do Componente | Descrição | Valor de Exemplo | Especificações | | ---------- | ------------------ | ---------------- | --------------------------------- | ------------------------------ | | `image` | `header_image` | URL da imagem | `"https://example.com/image.jpg"` | JPG, PNG, GIF - Máx 5MB | | `video` | `header_video` | URL do vídeo | `"https://example.com/video.mp4"` | MP4, AVI, MOV - Máx 16MB, 30s | | `document` | `header_document` | URL do documento | `"https://example.com/doc.pdf"` | PDF, DOC, XLS, PPT - Máx 100MB | **Nota**: `header_text` NÃO é um componente dinâmico. O texto do header é definido no template e não pode ser alterado. #### Componentes do Body (Apenas Variáveis) Texto do body com placeholders requer variáveis em ordem: `{"{1}"}`, `{"{2}"}`, `{"{3}"}`, etc. | Nome do Componente | Descrição | Mapeia para Placeholder | | ------------------ | ------------------------- | ----------------------- | | `body_text_0` | Primeira variável no body | `{"{1}"}` | | `body_text_1` | Segunda variável no body | `{"{2}"}` | | `body_text_2` | Terceira variável no body | `{"{3}"}` | | `body_text_N` | N-ésima variável no body | `{"{N}"}` | **Template de Exemplo**: "Olá `{"{1}"}`, seu curso `{"{2}"}` está pronto" * `body_text_0`: Valor para `{"{1}"}` (ex.: "Maria") * `body_text_1`: Valor para `{"{2}"}` (ex.: "JavaScript") #### Componentes do Footer ⚠️ **Footer é ESTÁTICO** - definido no template e não pode ser modificado por mensagem. #### Componentes de Botões **IMPORTANTE**: A maioria dos botões são ESTÁTICOS no template. No entanto, botões de URL com variáveis PODEM ser dinâmicos. | Nome do Componente | Descrição | Quando Aparece | | ------------------ | ----------------------------------------------------- | ---------------------------------------------------------- | | `buttons_url_0` | URL para primeiro botão de URL com variável `{"{1}"}` | Quando template tem botão de URL com placeholder `{"{1}"}` | | `buttons_url_1` | URL para segundo botão de URL com variável `{"{2}"}` | Quando template tem múltiplos botões de URL com variáveis | **Nota**: Botões de resposta rápida são sempre estáticos e não podem ser modificados por mensagem. *** ## 🧩 Variáveis do Template (Body Text) **CRÍTICO**: Variáveis em templates do WhatsApp usam **placeholders posicionais** como `{"{1}"}`, `{"{2}"}`, `{"{3}"}`, NÃO variáveis nomeadas como `{"{name}"}`. ### Como as Variáveis do Template Funcionam Templates do WhatsApp definem variáveis como placeholders numerados no texto do body do template: * Texto do template: "Olá `{"{1}"}`, seu curso `{"{2}"}` está pronto" * `{"{1}"}` mapeia para `body_text_0` * `{"{2}"}` mapeia para `body_text_1` ### Atribuição de Variáveis Você fornece os **valores** para esses placeholders numerados no objeto `components_push`: ```json theme={null} { "components_push": { "body_text_0": "María", "body_text_1": "JavaScript Advanced Course" } } ``` **Resultado**: "Olá María, seu curso JavaScript Advanced Course está pronto" ### Regras Importantes 1. **A ordem posicional importa**: `body_text_0` = `{"{1}"}`, `body_text_1` = `{"{2}"}`, etc. 2. **Valores diretos**: Forneça o valor real, não a sintaxe `{"{variable}"}` 3. **Todas as variáveis obrigatórias**: Deve fornecer valores para todos os placeholders `{"{N}"}` no template 4. **Sem mistura**: Não é possível combinar variáveis com texto estático em components\_push ### Resolução de Variáveis O sistema resolve referências `{"{variable}"}` em `components_push` buscando: 1. Primeiro no objeto `contact` 2. Depois nos parâmetros de nível raiz ```json theme={null} { "contact": { "name": "María", "email": "maria@example.com" }, "order_id": "ORD-12345", "components_push": { "body_text_0": "{{name}}", "body_text_1": "{{order_id}}" } } ``` *** ## ⏰ Agendamento e Fluxos de Conversa ### Entrega Imediata (Padrão) Se `datetime_sending` não for especificado, a mensagem é enviada imediatamente. ### Entrega Agendada Use `datetime_sending` e `timezone` para agendar mensagens. ### Integração com Fluxo de Conversa Use `name_event` para disparar fluxos de conversa específicos. *** ## 📊 Códigos de Resposta ### Resposta de Sucesso (200 OK) **Envio imediato:** ```json theme={null} { "success": true, "message": "Notification queued successfully", "notification_id": "uuid-notification-123" } ``` **Envio agendado:** ```json theme={null} { "success": true, "message": "Notification scheduled successfully", "notification_id": "uuid-notification-456", "scheduled_time": "2024-12-25T10:30:00Z" } ``` ### Respostas de Erro #### 400 Bad Request - Parâmetros Inválidos #### 401 Unauthorized - Chave de Acesso Inválida #### 404 Not Found - Template Não Encontrado #### 422 Unprocessable Entity - Erro de Lógica de Negócio #### 429 Too Many Requests - Limite de Taxa *** ## 🔧 Boas Práticas ### Estrutura de Dados * **Prefira estrutura aninhada** (`unflatten=false`) para melhor legibilidade * **Use estrutura plana** (`unflatten=true`) apenas quando seu sistema exigir * **Valide a estrutura** antes de enviar requisições ### Diretrizes de Mídia * **Use URLs HTTPS** para todos os arquivos de mídia * **Otimize tamanhos de arquivo** para entrega mais rápida * **Use URLs públicas** sem requisitos de autenticação * **Teste URLs de mídia** antes de enviar para garantir acessibilidade ### Agendamento * **Especifique fuso horário** ao usar `datetime_sending` * **Valide datas futuras** antes de agendar * **Considere horário comercial** para melhor engajamento * **Teste agendamento** em ambiente de desenvolvimento ### Desempenho * **Agrupe múltiplas notificações** quando possível * **Cache informações de templates** para reduzir chamadas de API * **Monitore limites de taxa** e implemente estratégias de backoff * **Use connection pooling** para melhor desempenho *** ## 📚 Documentação Relacionada * **[Autenticação](./authentication)** - Como obter tokens de acesso e chaves de API * **[Notificações de Voz](./voice_notifications)** - Enviar chamadas de voz automatizadas * **[Gerenciamento de Templates](./template_management)** - Criar e gerenciar templates do WhatsApp * **[Agendamento](./scheduling)** - Agendamento avançado e gerenciamento de fuso horário * **[Tratamento de Erros](./error_handling)** - Códigos de erro completos e estratégias de tratamento * **[Boas Práticas](./best_practices)** - Diretrizes de segurança e desempenho