API de Notificações WhatsApp - Lovi AI Documentation

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. 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:

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

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

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

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

Primeiro, chame o endpoint de componentes do template:

GET /notify/template/components?access_key={key}&template={template_id}

A API retorna apenas os componentes que você precisa fornecer:

{
  "status": "OK",
  "components": ["header_image", "body_text_0", "body_text_1"]
}

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

⚠️ 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:

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

A ordem posicional importa: body_text_0 = {"{1}"}, body_text_1 = {"{2}"}, etc.
Valores diretos: Forneça o valor real, não a sintaxe {"{variable}"}
Todas as variáveis obrigatórias: Deve fornecer valores para todos os placeholders {"{N}"} no template
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:

Primeiro no objeto contact
Depois nos parâmetros de nível raiz

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

{
  "success": true,
  "message": "Notification queued successfully",
  "notification_id": "uuid-notification-123"
}

Envio agendado:

{
  "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 - Como obter tokens de acesso e chaves de API
Notificações de Voz - Enviar chamadas de voz automatizadas
Gerenciamento de Templates - Criar e gerenciar templates do WhatsApp
Agendamento - Agendamento avançado e gerenciamento de fuso horário
Tratamento de Erros - Códigos de erro completos e estratégias de tratamento
Boas Práticas - Diretrizes de segurança e desempenho

Documentação API

Documentation Index

​Introdução

​Recursos Principais:

​📣 Enviar Notificação WhatsApp

​Endpoint

​Parâmetros de Query

​Headers

​📋 Parâmetros da Requisição

​Parâmetros Obrigatórios

​Parâmetros Opcionais

​👥 Destinatário Único vs Múltiplos

​Usando contact - Enviar para Uma Pessoa

​Usando contacts - Enviar para Múltiplas Pessoas (Envio em Massa)

​🔄 Formatos de Estrutura de Dados

​Estrutura Aninhada (unflatten=false ou omitido)

​Estrutura Plana (unflatten=true)

​Quando Usar Cada Formato

​🎨 Componentes e Multimídia

​Regras de Nomenclatura de Componentes

​Como Saber Quais Componentes Enviar

​Tipos de Componentes por Posição

​Componentes de Header (Apenas Mídia)

​Componentes do Body (Apenas Variáveis)

​Componentes do Footer

​Componentes de Botões

​🧩 Variáveis do Template (Body Text)

​Como as Variáveis do Template Funcionam

​Atribuição de Variáveis

​Regras Importantes

​Resolução de Variáveis

​⏰ Agendamento e Fluxos de Conversa

​Entrega Imediata (Padrão)

​Entrega Agendada

​Integração com Fluxo de Conversa

​📊 Códigos de Resposta

​Resposta de Sucesso (200 OK)

​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

​Diretrizes de Mídia

​Agendamento

​Desempenho

​📚 Documentação Relacionada