Saltar para o conteúdo principal

​
Introdução

Todos os endpoints de notificação da Lovi suportam agendamento para entrega futura. Este recurso permite enviar notificações em horários ideais considerando fusos horários dos destinatários e horário comercial.

​
📅 Parâmetros de Agendamento

Tanto notificações WhatsApp quanto de Voz suportam os seguintes parâmetros de agendamento:

​
Parâmetros

ParâmetroTipoObrigatórioDescriçãoExemplo
datetime_sendingDateTimeNãoData/hora agendada no formato ISO 8601"2024-12-25T10:30:00"
timezoneStringNãoFuso horário para o horário agendado"Europe/Madrid"
Comportamento Padrão: Se datetime_sending não for fornecido, a notificação é enviada imediatamente.

​
🕐 Formato de Datetime

​
Formatos ISO 8601 Suportados

{
  "datetime_sending": "2024-12-25T10:30:00",
  "timezone": "Europe/Madrid"
}
Formatos alternativos: 
"2024-12-25T10:30:00"
"2024-12-25T10:30:00.000"
"2024-12-25T10:30:00Z"
"2024-12-25T10:30:00+01:00"

​
Notas Importantes

  • Data Futura Obrigatória: O datetime deve estar no futuro
  • ISO 8601 Rigoroso: Use o formato padrão ISO 8601
  • Fuso Horário Recomendado: Sempre especifique o fuso horário para mensagens agendadas
  • UTC Padrão: Se o fuso horário for omitido, UTC é usado

​
🌍 Fusos Horários Suportados

​
Fusos Horários Comerciais Comuns

Região/PaísCódigo do Fuso HorárioDescrição
EspanhaEurope/MadridHorário da Europa Central
MéxicoAmerica/Mexico_CityHorário Padrão Central
ArgentinaAmerica/Argentina/Buenos_AiresHorário da Argentina
ColômbiaAmerica/BogotaHorário da Colômbia
ChileAmerica/SantiagoHorário Padrão do Chile
PeruAmerica/LimaHorário do Peru
EquadorAmerica/GuayaquilHorário do Equador
VenezuelaAmerica/CaracasHorário da Venezuela
BrasilAmerica/Sao_PauloHorário de Brasília
Estados UnidosAmerica/New_YorkHorário Padrão do Leste
Estados UnidosAmerica/ChicagoHorário Padrão Central
Estados UnidosAmerica/DenverHorário Padrão da Montanha
Estados UnidosAmerica/Los_AngelesHorário Padrão do Pacífico
UTCUTCCoordenado Universal

​
Fusos Horários Europeus

PaísCódigo do Fuso HorárioDescrição
Reino UnidoEurope/LondonHorário de Greenwich
FrançaEurope/ParisHorário da Europa Central
AlemanhaEurope/BerlinHorário da Europa Central
ItáliaEurope/RomeHorário da Europa Central
HolandaEurope/AmsterdamHorário da Europa Central
PortugalEurope/LisbonHorário da Europa Ocidental

​
📋 Exemplos

​
Notificação WhatsApp Agendada

Envio imediato (sem agendamento): 
{
  "contact": {
    "number": "34666033135",
    "name": "Ana García"
  },
  "language_template": "es_ES",
  "name_template": "promocion_navidad",
  "recipient_id": "34666033135",
  "notification_type": "marketing",
  "campaign_name": "Christmas Campaign"
}
Agendado para horário específico: 
{
  "contact": {
    "number": "34666033135",
    "name": "Ana García"
  },
  "language_template": "es_ES",
  "name_template": "promocion_navidad",
  "recipient_id": "34666033135",
  "notification_type": "marketing",
  "campaign_name": "Christmas Campaign",
  "datetime_sending": "2024-12-24T09:00:00",
  "timezone": "Europe/Madrid"
}

​
⚙️ Regras de Validação

​
Validação de Data

  • ✅ Apenas datas futuras: Deve ser posterior ao horário atual
  • ✅ Máximo de antecedência: Até 1 ano de antecedência
  • ✅ Formato rigoroso: Deve seguir ISO 8601
  • ❌ Datas passadas: Serão rejeitadas
  • ❌ Formato inválido: Datas não-ISO rejeitadas

​
Validação de Fuso Horário

  • ✅ Códigos IANA válidos: Use o banco de dados de fusos horários padrão
  • ✅ Sensível a maiúsculas: Formato exato obrigatório
  • ❌ Abreviações: Não use CET, EST, etc.
  • ❌ Códigos inválidos: Fusos horários desconhecidos rejeitados

​
🚀 Boas Práticas

​
Horário Ideal

Mensagens WhatsApp:
  • Horário comercial: 9:00 - 18:00 horário local
  • Evite cedo/tarde: Não antes das 8:00 ou após as 21:00
  • Consideração de final de semana: Ajuste para preferências de fim de semana
  • Atenção a feriados: Verifique feriados locais
Chamadas de Voz:
  • Apenas horário comercial: 9:00 - 17:00 horário local
  • Dias úteis preferidos: Segunda a Sexta
  • Horário de almoço: Evite 12:00 - 14:00
  • Sensibilidade cultural: Respeite costumes locais

​
Estratégia de Fuso Horário

  1. Armazene fusos dos usuários: Salve fuso horário preferido por contato
  2. Exibição em horário local: Mostre horários no fuso local do usuário
  3. Lógica de horário comercial: Calcule horários ideais de envio
  4. Horário de verão: Códigos IANA tratam DST automaticamente

​
Fluxo de Agendamento

​
🛠️ Dicas de Desenvolvimento

​
Testando Agendamento

  1. Use futuro próximo: Teste com horários 5-10 minutos à frente
  2. Teste de fuso horário: Teste diferentes cenários de fuso horário
  3. Casos limites: Teste transições de horário de verão
  4. Tratamento de erros: Teste com datas/fusos inválidos

​
Considerações de Produção

  • Tempo de buffer: Adicione 2-3 minutos de buffer para processamento
  • Monitoramento: Monitore horários agendados vs reais de envio
  • Lógica de retry: Trate falhas temporárias graciosamente
  • Logs: Registre detalhes de agendamento para debugging

​
Recursos de Fuso Horário

  • Banco de Dados IANA: Banco de dados oficial de fusos horários
  • Conversor online: Use ferramentas para verificar códigos de fuso horário
  • Documentação: Mantenha referência de fusos horários para desenvolvedores