Endpoint
POST /api/v1/messages/schedule
instanceId est l’identifiant technique requis pour planifier un message.
Pour l’obtenir :
- appeler
GET /api/v1/instances
- choisir l’instance souhaitée
- récupérer
data[n].id
- utiliser cette valeur dans
instanceId
Ne pas envoyer :
Body
| Champ | Type | Requis | Description |
|---|
instanceId | UUID | oui | Identifiant technique de l’instance MsgFlash, obtenu via GET /api/v1/instances |
to | string | oui | Numéro E.164 |
scheduledAt | ISO 8601 | oui | Date/heure d’envoi |
type | enum | oui si pas de templateId | text, image, video, audio, document, voice_note, location, contact, buttons |
templateId | UUID | oui si pas de type | Template à rendre |
variables | object | non | Valeurs custom.* |
/messages/send, y compris les champs spécifiques aux boutons (title, description, footer, buttons).
Exemple de requête
curl -X POST https://srv.msgflash.com/api/v1/messages/schedule \
-H "x-api-key: msgf_live_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"instanceId": "INSTANCE_UUID",
"to": "+33612345678",
"type": "text",
"text": "Bonjour dans 30 minutes",
"scheduledAt": "2026-04-02T08:00:00.000Z"
}'
Exemple avec boutons
curl -X POST https://srv.msgflash.com/api/v1/messages/schedule \
-H "x-api-key: msgf_live_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"instanceId": "INSTANCE_UUID",
"to": "+33612345678",
"type": "buttons",
"title": "Rappel programmé",
"description": "Votre rendez-vous est dans 30 minutes",
"scheduledAt": "2026-04-02T08:00:00.000Z",
"buttons": [
{
"type": "reply",
"displayText": "Confirmer",
"id": "confirm_appointment"
}
]
}'
Réponse succès 201
{
"data": {
"id": "msg_uuid",
"userId": "user_uuid",
"instanceId": "inst_uuid",
"contactId": null,
"campaignId": null,
"direction": "outbound",
"type": "text",
"from": null,
"to": "+33612345678",
"body": "Bonjour dans 30 minutes",
"mediaUrl": null,
"status": "queued",
"error": null,
"providerMessageId": null,
"warnings": [
"This instance is still in the warmup phase."
],
"safety": {
"decision": "warn",
"riskLevel": "medium",
"state": "warming",
"score": 56
},
"createdAt": "2026-04-02T07:30:00.000Z",
"updatedAt": "2026-04-02T07:30:00.000Z"
}
}
Les warnings safety sont informatifs. En V1, ils ne bloquent pas les messages planifiés.
Erreurs courantes
| HTTP | Code | Quand |
|---|
400 | VALIDATION_ERROR | Body invalide |
400 | TEMPLATE_INVALID | Template invalide |
404 | NOT_FOUND | Instance, contact ou template introuvable |
429 | MONTHLY_OUTBOUND_QUOTA_EXCEEDED | Quota déjà épuisé |
