Passer au contenu principal

​
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

{
  "recipients": {
    "type": "all"
  }
}
Pour tags, au moins un tag est requis. Pour explicit, au moins un contact est requis.

​
Types directs supportés

TypeContenu requis
textbody obligatoire
imagemediaUrl obligatoire, body optionnel
videomediaUrl obligatoire, body optionnel
documentmediaUrl obligatoire, body optionnel
audiomediaUrl obligatoire
voice_notemediaUrl 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

StatutDescription
draftRéservé à certains flux dashboard
scheduledEn attente de la date prévue
runningEn cours d’exécution
pausedPause manuelle
paused_quotaPause automatique pour quota
paused_planPause automatique pour plan/features
completedCampagne terminée
cancelledCampagne annulée
failedErreur 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ètreTypeRequisDescription
idUUIDouiID 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ètreTypeRequisDescription
idUUIDouiID de la campagne

​
Sens des compteurs

ChampDescription
plannedNombre total de messages générés pour la campagne
queuedMessages encore en file
sentMessages transmis à WhatsApp
deliveredMessages confirmés livrés
readMessages lus
failedÉchecs hors annulations
cancelledMessages 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ètreTypeRequisDescription
idUUIDouiID de la campagne

​
Erreurs courantes

CodeHTTPQuand
VALIDATION_ERROR400Campagne sans contenu, body manquant, media manquant ou destinataires invalides
CAMPAIGNS_NOT_AVAILABLE_ON_PLAN403Plan trop faible
NOT_FOUND404Instance ou template introuvable
MONTHLY_OUTBOUND_QUOTA_EXCEEDED429Quota épuisé