POST Créer une campagne

Endpoint

POST /api/v1/campaigns

Important — comment obtenir `instanceId`

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 :

name
waNumber

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"
      }
    ]
  }'

GET Récupérer un message GET Récupérer une campagne

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

POST Créer une campagne

Endpoint

Important — comment obtenir `instanceId`

Body

Règle de contenu

`recipients`

Réponse succès `201`

Erreurs courantes

Exemples

Campagne texte simple

Campagne avec boutons

​Endpoint

​Important — comment obtenir instanceId

​Body

​Règle de contenu

​recipients

​Réponse succès 201

​Erreurs courantes

​Exemples

​Campagne texte simple

​Campagne avec boutons

Endpoint

Important — comment obtenir `instanceId`

Body

Règle de contenu

`recipients`

Réponse succès `201`

Erreurs courantes

Exemples

Campagne texte simple

Campagne avec boutons