Programmation et gestion des fuseaux horaires

Introduction

Tous les endpoints de notification Lovi prennent en charge la programmation pour une livraison future. Cette fonctionnalité vous permet d’envoyer des notifications à des moments optimaux en tenant compte des fuseaux horaires des destinataires et des heures ouvrables.

📅 Paramètres de programmation

Les notifications WhatsApp et vocales prennent en charge les paramètres de programmation suivants :

Paramètres

Paramètre	Type	Requis	Description	Exemple
`datetime_sending`	DateTime	Non	Date/heure programmée au format ISO 8601	`"2024-12-25T10:30:00"`
`timezone`	String	Non	Fuseau horaire pour l’heure programmée	`"Europe/Madrid"`

Comportement par défaut : Si datetime_sending n’est pas fourni, la notification est envoyée immédiatement.

🕐 Format datetime

Formats ISO 8601 supportés

{
  "datetime_sending": "2024-12-25T10:30:00",
  "timezone": "Europe/Madrid"
}

Formats alternatifs :

"2024-12-25T10:30:00"
"2024-12-25T10:30:00.000"
"2024-12-25T10:30:00Z"
"2024-12-25T10:30:00+01:00"

Notes importantes

Date future requise : La date doit être dans le futur
ISO 8601 strict : Utilisez le format standard ISO 8601
Fuseau horaire recommandé : Spécifiez toujours le fuseau horaire pour les messages programmés
UTC par défaut : Si le fuseau horaire est omis, UTC est utilisé

🌍 Fuseaux horaires supportés

Fuseaux horaires professionnels courants

Région/Pays	Code fuseau horaire	Description
Espagne	`Europe/Madrid`	Heure d’Europe centrale
Mexique	`America/Mexico_City`	Heure normale du Centre
Argentine	`America/Argentina/Buenos_Aires`	Heure d’Argentine
Colombie	`America/Bogota`	Heure de Colombie
Chili	`America/Santiago`	Heure normale du Chili
Pérou	`America/Lima`	Heure du Pérou
Équateur	`America/Guayaquil`	Heure de l’Équateur
Venezuela	`America/Caracas`	Heure du Venezuela
États-Unis	`America/New_York`	Heure normale de l’Est
États-Unis	`America/Chicago`	Heure normale du Centre
États-Unis	`America/Denver`	Heure normale des Rocheuses
États-Unis	`America/Los_Angeles`	Heure normale du Pacifique
UTC	`UTC`	Temps universel coordonné

Fuseaux horaires européens

Pays	Code fuseau horaire	Description
Royaume-Uni	`Europe/London`	Heure de Greenwich
France	`Europe/Paris`	Heure d’Europe centrale
Allemagne	`Europe/Berlin`	Heure d’Europe centrale
Italie	`Europe/Rome`	Heure d’Europe centrale
Pays-Bas	`Europe/Amsterdam`	Heure d’Europe centrale
Portugal	`Europe/Lisbon`	Heure d’Europe occidentale

📋 Exemples

Notification WhatsApp programmée

Envoi immédiat (sans programmation) :

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

Programmé pour une heure spécifique :

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

Notification vocale programmée

{
  "contact": {
    "number": "34666033135",
    "first_name": "María",
    "last_name": "González"
  },
  "recipient_id": "34911670470",
  "agent_id": "uuid-agente-voz",
  "notification_type": "marketing",
  "campaign_name": "Voice Campaign",
  "datetime_sending": "2024-12-26T10:00:00",
  "timezone": "Europe/Madrid"
}

Structure plate avec programmation (unflatten=true)

{
  "contact.number": "34666033135",
  "contact.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"
}

⚙️ Règles de validation

Validation des dates

✅ Dates futures uniquement : Doit être postérieur à l’heure actuelle
✅ Avance maximale : Jusqu’à 1 an à l’avance
✅ Format strict : Doit suivre ISO 8601
❌ Dates passées : Seront rejetées
❌ Format invalide : Dates non-ISO rejetées

Validation des fuseaux horaires

✅ Codes IANA valides : Utilisez la base de données standard des fuseaux horaires
✅ Sensible à la casse : Format exact requis
❌ Abréviations : N’utilisez pas CET, EST, etc.
❌ Codes invalides : Fuseaux horaires inconnus rejetés

Exemples valides/invalides

✅ Valide :

{
  "datetime_sending": "2024-12-25T14:30:00",
  "timezone": "America/Mexico_City"
}

❌ Datetime invalide :

{
  "datetime_sending": "25/12/2024 14:30",  // Mauvais format
  "timezone": "Europe/Madrid"
}

❌ Fuseau horaire invalide :

{
  "datetime_sending": "2024-12-25T14:30:00",
  "timezone": "CET"  // Utilisez Europe/Madrid à la place
}

🚀 Bonnes pratiques

Timing optimal

Messages WhatsApp :

Heures ouvrables : 9h00 - 18h00 heure locale
Évitez tôt/tard : Pas avant 8h00 ni après 21h00
Considération week-end : Ajustez selon les préférences du week-end
Sensibilité aux jours fériés : Vérifiez les jours fériés locaux

Appels vocaux :

Heures ouvrables uniquement : 9h00 - 17h00 heure locale
Jours ouvrés préférés : Du lundi au vendredi
Heures de déjeuner : Évitez 12h00 - 14h00
Sensibilité culturelle : Respectez les coutumes locales

Stratégie de fuseaux horaires

Stockez les fuseaux horaires des utilisateurs : Enregistrez le fuseau horaire préféré par contact
Affichage en heure locale : Affichez les heures dans le fuseau horaire local de l’utilisateur
Logique d’heures ouvrables : Calculez les heures d’envoi optimales
Heure d’été : Les codes IANA gèrent automatiquement le changement d’heure

Flux de programmation

📊 Exemples de réponse

Programmation réussie

{
  "success": true,
  "message": "Notification scheduled successfully",
  "notification_id": "uuid-notification-123",
  "scheduled_time": "2024-12-25T10:30:00Z",
  "local_time": "2024-12-25T11:30:00+01:00",
  "timezone": "Europe/Madrid"
}

Envoi immédiat

{
  "success": true,
  "message": "Notification queued for immediate sending",
  "notification_id": "uuid-notification-456",
  "queued_at": "2024-12-20T15:45:30Z"
}

⚠️ Erreurs courantes

Erreur de date passée

{
  "error": "validation_failed",
  "message": "Scheduled time must be in the future",
  "details": {
    "field": "datetime_sending",
    "provided": "2024-12-20T10:00:00",
    "current_time": "2024-12-20T15:30:00Z"
  }
}

Erreur de fuseau horaire invalide

{
  "error": "validation_failed",
  "message": "Invalid timezone specified",
  "details": {
    "field": "timezone",
    "provided": "CET",
    "suggestion": "Use IANA timezone codes like 'Europe/Madrid'"
  }
}

Erreur de format invalide

{
  "error": "validation_failed",
  "message": "Invalid datetime format",
  "details": {
    "field": "datetime_sending",
    "provided": "25-12-2024 10:30",
    "expected_format": "ISO 8601 (YYYY-MM-DDTHH:MM:SS)"
  }
}

🛠️ Conseils de développement

Test de la programmation

Utilisez le futur proche : Testez avec des heures 5-10 minutes en avance
Test des fuseaux horaires : Testez différents scénarios de fuseaux horaires
Cas limites : Testez les transitions d’heure d’été
Gestion des erreurs : Testez avec des dates/fuseaux horaires invalides

Considérations pour la production

Temps tampon : Ajoutez 2-3 minutes de tampon pour le traitement
Surveillance : Surveillez les heures d’envoi programmées vs réelles
Logique de retry : Gérez les échecs temporaires gracieusement
Journaux : Journalisez les détails de programmation pour le débogage

Ressources fuseaux horaires

Base de données IANA : Base de données officielle des fuseaux horaires
Convertisseur en ligne : Utilisez des outils pour vérifier les codes de fuseaux horaires
Documentation : Gardez une référence des fuseaux horaires pour les développeurs

​Introduction

​📅 Paramètres de programmation

​Paramètres

​🕐 Format datetime

​Formats ISO 8601 supportés

​Notes importantes

​🌍 Fuseaux horaires supportés

​Fuseaux horaires professionnels courants

​Fuseaux horaires européens

​📋 Exemples

​Notification WhatsApp programmée

​Notification vocale programmée

​Structure plate avec programmation (unflatten=true)

​⚙️ Règles de validation

​Validation des dates

​Validation des fuseaux horaires

​Exemples valides/invalides

​🚀 Bonnes pratiques

​Timing optimal

​Stratégie de fuseaux horaires

​Flux de programmation

​📊 Exemples de réponse

​Programmation réussie

​Envoi immédiat

​⚠️ Erreurs courantes

​Erreur de date passée

​Erreur de fuseau horaire invalide

​Erreur de format invalide

​🛠️ Conseils de développement

​Test de la programmation

​Considérations pour la production

​Ressources fuseaux horaires