Gestion des Campagnes SMS

Les campagnes SMS vous permettent d’envoyer des messages personnalisés à un groupe de destinataires. Notre SDK offre une solution complète pour créer et gérer vos campagnes, avec support pour les messages standards, programmés et répétés.

Fonctionnalités

Envoi de messages personnalisés
Support des messages programmés
Support des messages répétés
Gestion des groupes de destinataires
Personnalisation des expéditeurs
Suivi des campagnes

Types de campagnes

Notre API supporte plusieurs types de campagnes :

Campagnes standards : Envoi immédiat de messages
Campagnes programmées : Envoi à une date et heure précises
Campagnes répétées : Envoi récurrent selon un planning défini

Limites des messages

Les SMS sont soumis à des limites de caractères selon l’encodage utilisé :

GSM-7 : 160 caractères par message
UCS-2 : 70 caractères par message (pour les caractères spéciaux)
Messages longs : Segmentation automatique (153 caractères par segment)

⚠️

Important : Incluez l’indicatif du pays sans le symbole (+) avant le numéro de téléphone. Exemple : “22500000000” pour un numéro ivoirien.

Utilisation

Après avoir initialisé votre bibliothèque, vous pouvez utiliser la propriété campain pour gérer vos campagnes SMS.

Création d’une campagne

/api/campain


import { sms } from "@/libs/sms";
 
const createCampain = async () => {
  try {
    // Création d'une nouvelle campagne avec contacts, message et expéditeur
    const res = await sms.campain.create({
      contacts: [
        // saved contact
        {
          id: "contact_1",
          phone: "22500000000",
          name: "John Doe",
        },
        // new contact (will be saved if number does not exist)
        {
          phone: "2250101010101",
        },
      ],
      groupsIds: ["group_1", "group_2"], // will add groups contacts to the campain
      text: "Bonjour @nom_complet bon début de semaine.",
      senderId: "My Sender", // will go if active or will use the default sender
    });
 
    console.log(res);
  } catch (error) {
    console.error(error);
  }
};

Création d’une campagne programmée

/api/campain/scheduled


import { sms } from "@/libs/sms";
 
const createScheduledCampain = async () => {
  try {
    // Création d'une campagne programmée
    const res = await sms.campain.create({
      contacts: [
        {
          id: "contact_1",
          phone: "22500000000",
          name: "John Doe",
        },
      ],
      text: "Rappel : Votre rendez-vous est demain à 10h.",
      senderId: "My Sender",
      type: "SCHEDULED",
      scheduledDate: new Date("2024-03-20T10:00:00Z"), // checking date and time
    });
 
    console.log(res);
  } catch (error) {
    console.error(error);
  }
};

⚠️

Important : Les dates programmées doivent être des multiples de 15 minutes. Par exemple : 10:00, 10:15, 10:30, 10:45.

Création d’une campagne répétée

/api/campain/recurring


import { sms } from "@/libs/sms";
 
const createRecurringCampain = async () => {
  try {
    // Création d'une campagne répétée
    const res = await sms.campain.create({
      contacts: [
        {
          id: "contact_1",
          phone: "22500000000",
          name: "John Doe",
        },
      ],
      text: "Rappel hebdomadaire : N'oubliez pas votre séance.",
      senderId: "My Sender",
      type: "RECURRING",
      recurring: {
        monday: new Date("2024-03-18T09:00:00Z"), // checking day and time, not the date
        wednesday: new Date("2024-03-20T09:00:00Z"), // checking day and time, not the date
        friday: new Date("2024-03-22T09:00:00Z"), // checking day and time, not the date
      },
    });
 
    console.log(res);
  } catch (error) {
    console.error(error);
  }
};

⚠️

Important : Les heures de répétition doivent être des multiples de 15 minutes. Par exemple : 09:00, 09:15, 09:30, 09:45.

La variable sms est l’instance initialisée de notre SDK. Elle fournit la méthode create pour lancer de nouvelles campagnes SMS avec des options de personnalisation avancées.

Documentation de l’API

sms.campain.create

Crée une nouvelle campagne SMS avec les paramètres spécifiés.

Nom	Description	Type	Facultatif	Valeur par défaut
name	Nom de la campagne	Texte	Oui
contacts	Liste des contacts destinataires	Array de Contact Object	Non
groupsIds	Liste des identifiants de groupes	Array de Texte	Oui	[]
text	Contenu du message	Texte	Non
senderId	Identifiant de l’expéditeur	Texte	Oui
type	Type de campagne	”SMS” \| “SCHEDULED” \| “RECURRING”	Oui	SMS
scheduledDate	Date de programmation (pour type SCHEDULED)	Date	Oui	undefined
recurring	Configuration des répétitions (pour type RECURRING)	Object	Oui	undefined

Structure des contacts


type Contact = {
  id?: string; // Identifiant unique du contact (optionnel)
  phone: string; // Numéro de téléphone (format: 22500000000)
  name?: string; // Nom complet du contact (optionnel)
  firstName?: string; // Prénom du contact (optionnel)
  lastName?: string; // Nom de famille du contact (optionnel)
  sex?: "M" | "F"; // Genre du contact (optionnel)
};

Seul le numéro de téléphone (phone) est obligatoire. Tous les autres champs sont optionnels. Si un contact n’existe pas, il sera automatiquement créé avec les informations fournies.

Configuration des répétitions


type RecurringConfig = {
  monday?: Date;
  tuesday?: Date;
  wednesday?: Date;
  thursday?: Date;
  friday?: Date;
  saturday?: Date;
  sunday?: Date;
};

Liste des campagnes

Vous pouvez récupérer la liste de vos campagnes avec leurs détails de base.

/api/campain/list


import { sms } from "@/libs/sms";
 
const listCampaigns = async () => {
  try {
    // Récupération de la liste des campagnes
    const res = await sms.campain.list();
 
    console.log(res);
  } catch (error) {
    console.error(error);
  }
};

Paramètres de la liste

Nom	Description	Type	Facultatif	Valeur par défaut
page	Numéro de page	Nombre	Oui	1
limit	Nombre d’éléments par page	Nombre	Oui	10
status	Filtre par statut	”ALL” \| “PENDING” \| “SENT” \| “FAILED”	Oui	”ALL”

Détails d’une campagne

Vous pouvez récupérer les détails complets d’une campagne spécifique.

/api/campain/details


import { sms } from "@/libs/sms";
 
const getCampaignDetails = async () => {
  try {
    // Récupération des détails d'une campagne
    const res = await sms.campain.get("campaign_id");
 
    console.log(res);
  } catch (error) {
    console.error(error);
  }
};

Structure de réponse


type CampaignDetails = {
  id: string; // Identifiant unique de la campagne
  name: string; // Nom de la campagne
  type: "SMS" | "SCHEDULED" | "RECURRING"; // Type de campagne
  status: "PENDING" | "SENT" | "FAILED"; // Statut de la campagne
  text: string; // Contenu du message
  senderId: string; // Identifiant de l'expéditeur
  scheduledDate?: Date; // Date de programmation (pour type SCHEDULED)
  recurring?: RecurringConfig; // Configuration des répétitions (pour type RECURRING)
  contacts: Contact[]; // Liste des contacts destinataires
  stats: {
    total: number; // Nombre total de messages
    sent: number; // Nombre de messages envoyés
    failed: number; // Nombre de messages échoués
    pending: number; // Nombre de messages en attente
  };
  createdAt: Date; // Date de création
  updatedAt: Date; // Date de dernière mise à jour
};

Les détails d’une campagne incluent des statistiques en temps réel sur l’état d’envoi des messages et la liste complète des contacts destinataires.

Bonnes pratiques

Longueur des messages : Respectez les limites de caractères
Personnalisation : Utilisez les variables disponibles (@nom_complet, etc.)
Expéditeur : Choisissez un senderId reconnu
Test : Vérifiez vos messages avant envoi
Segmentation : Évitez les messages trop longs
Programmation : Vérifiez les fuseaux horaires pour les campagnes programmées
Répétitions : Testez les campagnes répétées sur un petit groupe
Intervalles : Utilisez des intervalles de 15 minutes pour les campagnes programmées et répétées

Cas d’utilisation

Campagnes marketing
Notifications clients
Alertes et rappels
Communications internes
Service client
Rappels de rendez-vous
Alertes de sécurité

FAQ

Comment personnaliser mes messages ?

Utilisez les variables comme @nom_complet dans votre texte pour personnaliser automatiquement chaque message.

Comment gérer les messages longs ?

Les messages dépassant la limite de caractères sont automatiquement segmentés, chaque segment étant facturé séparément.

Puis-je envoyer à des groupes ?

Oui, utilisez le paramètre groupsIds pour envoyer à des groupes de contacts prédéfinis.

Comment programmer une campagne ?

Utilisez le type “SCHEDULED” avec le paramètre scheduledDate pour définir la date et l’heure d’envoi.

Comment créer une campagne répétée ?

Utilisez le type “RECURRING” avec le paramètre recurring pour définir les jours et heures de répétition.