Campaigns

Endpoint

POST /api/v1/campaigns

Authentication: x-api-key: <api_key>

Campaigns require the Starter plan or higher.

Main business rule

A campaign must include actual content to send. Vous devez fournir :

name
instanceId
schedule
recipients

Et exactement un mode de contenu :

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

Creating an empty campaign is not allowed.

Mode 1 — Template campaign

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": "noe",
    "templateId": "YOUR_TEMPLATE_ID",
    "variables": {
      "campaignName": "Black Friday"
    },
    "recipients": {
      "type": "all"
    }
  }'

Mode 2 — Direct text campaign

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": "noe",
    "type": "text",
    "body": "Hello, votre panier vous attend encore.",
    "recipients": {
      "type": "explicit",
      "value": ["CONTACT_UUID_1", "CONTACT_UUID_2"]
    }
  }'

Mode 3 — Direct media campaign

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": "noe",
    "type": "image",
    "body": "Découvrez notre offre de la semaine",
    "mediaUrl": "https://cdn.example.com/promo.jpg",
    "recipients": {
      "type": "all"
    }
  }'

Recipients

Tous les contacts
Par tags
List explicite

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

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

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

For tags, at least one tag is required. For explicit, at least one contact is required.

Types directs supportés

Type	Required content
`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

Response à 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
    }
  }
}

The response can include a safety block with decision, riskLevel, reasons, and recommendations. In V1, this guidance does not block the campaign.

Campaign statuses

Status	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`	Campaign completed
`cancelled`	Campaign cancelled
`failed`	Fatal error

A campaign now automatically moves to completed when no queued messages remain.

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"

These actions are valid only for compatible statuses. resume can also return a safety block if the instance is still warming up or if the audience is riskier than recommended.

Parameters path

Parameter	Type	Required	Description
`id`	UUID	yes	Campaign ID

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
  }
}

Parameters path

Parameter	Type	Required	Description
`id`	UUID	yes	Campaign ID

Sens des compteurs

Field	Description
`planned`	Total number of messages generated for the campaign
`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

Retrieve a campaign

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

Parameters path

Parameter	Type	Required	Description
`id`	UUID	yes	Campaign ID

Common errors

Code	HTTP	When
`VALIDATION_ERROR`	400	Empty campaign, missing body, missing media, or invalid recipients
`CAMPAIGNS_NOT_AVAILABLE_ON_PLAN`	403	Plan trop faible
`NOT_FOUND`	404	Instance ou template not found
`MONTHLY_OUTBOUND_QUOTA_EXCEEDED`	429	Quota exhausted

Getting Started

Guides

API Reference · Teams

API Reference · Instances

API Reference · Messages

API Reference · Campaigns

API Reference · Templates

API Reference · Contacts

API Reference · Groups

API Reference · Number Lookups

API Reference · Webhooks

API Reference · Billing

Resources

Endpoint

Main business rule

Mode 1 — Template campaign

Mode 2 — Direct text campaign

Mode 3 — Direct media campaign

Recipients

Types directs supportés

Response à la création

Campaign statuses

Pauser et reprendre

Parameters path

Statistiques

Parameters path

Sens des compteurs

Retrieve a campaign

Parameters path

Common errors

​Endpoint

​Main business rule

​Mode 1 — Template campaign

​Mode 2 — Direct text campaign

​Mode 3 — Direct media campaign

​Recipients

​Types directs supportés

​Response à la création

​Campaign statuses

​Pauser et reprendre

​Parameters path

​Statistiques

​Parameters path

​Sens des compteurs

​Retrieve a campaign

​Parameters path

​Common errors

Endpoint

Main business rule

Mode 1 — Template campaign

Mode 2 — Direct text campaign

Mode 3 — Direct media campaign

Recipients

Types directs supportés

Response à la création

Campaign statuses

Pauser et reprendre

Parameters path

Statistiques

Parameters path

Sens des compteurs

Retrieve a campaign

Parameters path

Common errors