Campagnes

Endpoint

POST /api/v1/campaigns

Authentification : x-api-key: <api_key>

Les campagnes nécessitent le plan Starter ou supérieur.

Règle métier principale

Une campagne doit contenir un vrai contenu à envoyer. Vous devez fournir :

name
instanceId
schedule
recipients

Et exactement un mode de contenu :

soit templateId
soit un message direct avec type + contenu associé

Il est interdit de créer une campagne vide.

Mode 1 — Campagne template

curl -X POST https://srv.msgflash.com/api/v1/campaigns \
  -H "x-api-key: msgf_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "YOUR_INSTANCE_ID",
    "name": "Promo Black Friday",
    "schedule": "2026-04-02T10:00:00.000Z",
    "repeat": "none",
    "templateId": "YOUR_TEMPLATE_ID",
    "variables": {
      "campaignName": "Black Friday"
    },
    "recipients": {
      "type": "all"
    }
  }'

Mode 2 — Campagne message direct texte

curl -X POST https://srv.msgflash.com/api/v1/campaigns \
  -H "x-api-key: msgf_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "YOUR_INSTANCE_ID",
    "name": "Relance panier",
    "schedule": "2026-04-02T10:00:00.000Z",
    "repeat": "none",
    "type": "text",
    "body": "Bonjour, votre panier vous attend encore.",
    "recipients": {
      "type": "explicit",
      "value": ["CONTACT_UUID_1", "CONTACT_UUID_2"]
    }
  }'

Mode 3 — Campagne message direct média

curl -X POST https://srv.msgflash.com/api/v1/campaigns \
  -H "x-api-key: msgf_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "YOUR_INSTANCE_ID",
    "name": "Promo visuelle",
    "schedule": "2026-04-02T10:00:00.000Z",
    "repeat": "none",
    "type": "image",
    "body": "Découvrez notre offre de la semaine",
    "mediaUrl": "https://cdn.example.com/promo.jpg",
    "recipients": {
      "type": "all"
    }
  }'

Destinataires

Tous les contacts
Par tags
Liste explicite

{
  "recipients": {
    "type": "all"
  }
}

{
  "recipients": {
    "type": "tags",
    "value": ["vip", "newsletter"]
  }
}

{
  "recipients": {
    "type": "explicit",
    "value": ["CONTACT_UUID_1", "CONTACT_UUID_2"]
  }
}

Pour tags, au moins un tag est requis. Pour explicit, au moins un contact est requis.

Types directs supportés

Type	Contenu requis
`text`	`body` obligatoire
`image`	`mediaUrl` obligatoire, `body` optionnel
`video`	`mediaUrl` obligatoire, `body` optionnel
`document`	`mediaUrl` obligatoire, `body` optionnel
`audio`	`mediaUrl` obligatoire
`voice_note`	`mediaUrl` obligatoire

Réponse à la création

{
  "data": {
    "id": "cmp_uuid",
    "instanceId": "inst_uuid",
    "templateId": "tmpl_uuid",
    "type": null,
    "body": null,
    "mediaUrl": null,
    "name": "Promo Black Friday",
    "schedule": "2026-04-02T10:00:00.000Z",
    "status": "scheduled",
    "recipients": { "type": "all" },
    "stats": {
      "planned": 0,
      "queued": 0,
      "sent": 0,
      "delivered": 0,
      "read": 0,
      "failed": 0,
      "cancelled": 0,
      "processingStartedAt": null,
      "lastEnqueuedAt": null,
      "completedAt": null,
      "cancelledAt": null
    }
  }
}

La réponse peut contenir un bloc safety avec decision, riskLevel, reasons et recommendations. En V1, cette guidance ne bloque pas la campagne.

Statuts d’une campagne

Statut	Description
`draft`	Réservé à certains flux dashboard
`scheduled`	En attente de la date prévue
`running`	En cours d’exécution
`paused`	Pause manuelle
`paused_quota`	Pause automatique pour quota
`paused_plan`	Pause automatique pour plan/features
`completed`	Campagne terminée
`cancelled`	Campagne annulée
`failed`	Erreur fatale

Une campagne passe maintenant automatiquement à completed quand il ne reste plus de messages queued.

Pauser et reprendre

curl -X POST https://srv.msgflash.com/api/v1/campaigns/CAMPAIGN_ID/pause \
  -H "x-api-key: msgf_live_your_api_key_here"

curl -X POST https://srv.msgflash.com/api/v1/campaigns/CAMPAIGN_ID/resume \
  -H "x-api-key: msgf_live_your_api_key_here"

Ces actions sont valides uniquement sur les statuts compatibles. Le resume peut lui aussi retourner un bloc safety si l’instance est encore en warmup ou si l’audience est plus risquée que recommandé.

Paramètres path

Paramètre	Type	Requis	Description
`id`	UUID	oui	ID de la campagne

Statistiques

curl https://srv.msgflash.com/api/v1/campaigns/CAMPAIGN_ID/stats \
  -H "x-api-key: msgf_live_your_api_key_here"

{
  "data": {
    "campaignId": "cmp_uuid",
    "status": "running",
    "stats": {
      "total": 1000,
      "planned": 1000,
      "queued": 150,
      "sent": 600,
      "delivered": 580,
      "read": 420,
      "failed": 10,
      "cancelled": 5
    },
    "progressPercent": 85,
    "timeline": {
      "scheduledFor": "2026-04-02T10:00:00.000Z",
      "processingStartedAt": "2026-04-02T10:00:01.000Z",
      "lastEnqueuedAt": "2026-04-02T10:03:20.000Z",
      "completedAt": null,
      "cancelledAt": null,
      "lastActivityAt": "2026-04-02T10:04:12.000Z"
    },
    "startedAt": "2026-04-02T10:00:01.000Z",
    "estimatedCompletionAt": null
  }
}

Paramètres path

Paramètre	Type	Requis	Description
`id`	UUID	oui	ID de la campagne

Sens des compteurs

Champ	Description
`planned`	Nombre total de messages générés pour la campagne
`queued`	Messages encore en file
`sent`	Messages transmis à WhatsApp
`delivered`	Messages confirmés livrés
`read`	Messages lus
`failed`	Échecs hors annulations
`cancelled`	Messages marqués annulés

Récupérer une campagne

curl https://srv.msgflash.com/api/v1/campaigns/CAMPAIGN_ID \
  -H "x-api-key: msgf_live_your_api_key_here"

Paramètres path

Paramètre	Type	Requis	Description
`id`	UUID	oui	ID de la campagne

Erreurs courantes

Code	HTTP	Quand
`VALIDATION_ERROR`	400	Campagne sans contenu, body manquant, media manquant ou destinataires invalides
`CAMPAIGNS_NOT_AVAILABLE_ON_PLAN`	403	Plan trop faible
`NOT_FOUND`	404	Instance ou template introuvable
`MONTHLY_OUTBOUND_QUOTA_EXCEEDED`	429	Quota épuisé

Pour commencer

Guides

Référence API · Équipes

Référence API · Instances

Référence API · Messages

Référence API · Campagnes

Référence API · Modèles

Référence API · Contacts

Référence API · Groupes

Référence API · Number lookups

Référence API · Webhooks

Référence API · Facturation

Ressources

Endpoint

Règle métier principale

Mode 1 — Campagne template

Mode 2 — Campagne message direct texte

Mode 3 — Campagne message direct média

Destinataires

Types directs supportés

Réponse à la création

Statuts d’une campagne

Pauser et reprendre

Paramètres path

Statistiques

Paramètres path

Sens des compteurs

Récupérer une campagne

Paramètres path

Erreurs courantes

​Endpoint

​Règle métier principale

​Mode 1 — Campagne template

​Mode 2 — Campagne message direct texte

​Mode 3 — Campagne message direct média

​Destinataires

​Types directs supportés

​Réponse à la création

​Statuts d’une campagne

​Pauser et reprendre

​Paramètres path

​Statistiques

​Paramètres path

​Sens des compteurs

​Récupérer une campagne

​Paramètres path

​Erreurs courantes

Endpoint

Règle métier principale

Mode 1 — Campagne template

Mode 2 — Campagne message direct texte

Mode 3 — Campagne message direct média

Destinataires

Types directs supportés

Réponse à la création

Statuts d’une campagne

Pauser et reprendre

Paramètres path

Statistiques

Paramètres path

Sens des compteurs

Récupérer une campagne

Paramètres path

Erreurs courantes