Endpoint
instanceId est obligatoire pour créer une campagne.
Pour l’obtenir :
- appeler
GET /api/v1/instances
- choisir une instance avec
status = "connected" si possible
- récupérer
data[n].id
- envoyer cette valeur dans
instanceId
Ne pas utiliser à la place :
Body
| Champ | Type | Requis | Description |
|---|
instanceId | UUID | oui | Identifiant technique de l’instance MsgFlash, obtenu via GET /api/v1/instances |
name | string | oui | Nom interne |
schedule | ISO 8601 | oui | Date de démarrage |
repeat | string | non | none, daily, weekly |
recipients | object | oui | Sélecteur de destinataires |
templateId | UUID | oui si mode template | Template utilisé |
variables | object | non | Variables custom.* globales |
type | enum | oui si mode direct | text, image, video, audio, document, voice_note, buttons |
body | string | selon type | Obligatoire pour text, optionnel pour certains médias |
mediaUrl | string | selon type | Obligatoire pour les types média |
title | string | si buttons | Titre du message boutons |
description | string | si buttons | Description du message boutons |
footer | string | non | Pied de page du message boutons |
buttons | array | si buttons | Liste des boutons (max 2) |
Règle de contenu
Une campagne doit avoir exactement un mode de contenu :
- soit
templateId
- soit
type + contenu direct
Ne pas envoyer les deux en même temps.
recipients
| Champ | Type | Requis | Description |
|---|
type | enum | oui | all, tags, explicit, group |
value | string[] | selon type | Tags ou IDs de contacts |
groupId | UUID | si type=group | Groupe cible |
Réponse succès 201
{
"data": {
"id": "cmp_uuid",
"userId": "user_uuid",
"instanceId": "inst_uuid",
"name": "Newsletter Avril",
"status": "scheduled",
"templateId": "tmpl_uuid",
"type": null,
"body": null,
"mediaUrl": null,
"schedule": "2026-04-15T09:00:00.000Z",
"repeat": "none",
"recipients": {
"type": "all"
},
"stats": {
"planned": 0,
"queued": 0,
"sent": 0,
"delivered": 0,
"read": 0,
"failed": 0,
"cancelled": 0
},
"safety": {
"decision": "warn",
"riskLevel": "medium",
"score": 56,
"state": "warming",
"reasons": [
"This instance is still warming up and campaign pacing should stay gradual."
],
"recommendations": [
"Start with previously engaged contacts before scaling volume."
],
"appliedLimits": {
"maxCampaignRecipients": 100,
"maxColdRatio": 0.4
},
"audience": {
"totalRecipients": 120,
"coldRatio": 0.625
}
},
"createdAt": "2026-04-10T09:00:00.000Z",
"updatedAt": "2026-04-10T09:00:00.000Z"
}
}
En V1, safety.decision vaut allow ou warn. Un warning n’empêche pas la création de la campagne.
Erreurs courantes
| HTTP | Code | Quand |
|---|
400 | VALIDATION_ERROR | Campagne vide, body manquant, media manquant, destinataires invalides |
403 | CAMPAIGNS_NOT_AVAILABLE_ON_PLAN | Plan trop faible |
403 | UNSUPPORTED_FEATURE | Fonctionnalité non supportée (boutons sans WhatsApp Business) |
404 | NOT_FOUND | Instance ou template introuvable |
Exemples
Campagne texte simple
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": "INSTANCE_UUID",
"name": "Newsletter Avril",
"schedule": "2026-04-15T09:00:00.000Z",
"recipients": {
"type": "all"
},
"type": "text",
"body": "Découvrez nos nouvelles offres !"
}'
Campagne avec boutons
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": "INSTANCE_UUID",
"name": "Sondage satisfaction",
"schedule": "2026-04-15T10:00:00.000Z",
"recipients": {
"type": "tags",
"value": ["client"]
},
"type": "buttons",
"title": "Votre avis compte !",
"description": "Êtes-vous satisfait de nos services ?",
"footer": "Répondez avant demain",
"buttons": [
{
"type": "reply",
"displayText": "Très satisfait",
"id": "satisfied"
},
{
"type": "reply",
"displayText": "À améliorer",
"id": "needs_improvement"
}
]
}'
