Schedule a message

Endpoint

POST /api/v1/messages/schedule

Authentication: x-api-key: <api_key> The difference from /messages/send is the scheduledAt field.

Parameters

Body

Field	Type	Required	Description
`instanceId`	UUID	yes	Instance WhatsApp
`to`	string	yes	Number destinataire
`scheduledAt`	ISO 8601	yes	Date future d’envoi
`type`	enum	yes if no `templateId`	Direct message type
`templateId`	UUID	yes if no `type`	Template to render
`variables`	object	no	`custom.*` values

Pas de path params ni query params.

Example

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": "YOUR_INSTANCE_ID",
    "to": "+33612345678",
    "templateId": "TEMPLATE_UUID",
    "contactId": "CONTACT_UUID",
    "variables": {
      "code": "PROMO10"
    },
    "scheduledAt": "2026-04-02T08:00:00.000Z"
  }'

Other fields follow the same rules as Send a message.

Response

{
  "data": {
    "id": "msg_uuid",
    "status": "queued",
    "body": "Hello Awa, votre code PROMO10 est prêt."
  }
}

Le message reste en queued jusqu’au traitement effectif.

Common errors

Code	HTTP	When
`VALIDATION_ERROR`	400	Invalid body
`TEMPLATE_INVALID`	400	Template invalid
`TEMPLATE_VARIABLES_MISSING`	400	Variables template missing
`NOT_FOUND`	404	Instance, contact, or template not found
`MONTHLY_OUTBOUND_QUOTA_EXCEEDED`	429	Quota already exhausted au moment de la planification

Important rules

scheduledAt est attendu en UTC
une date passée est acceptée et conduit à un envoi immediat
le quota monthly est vérifié à la planification puis au moment de l’envoi effectif
si l’instance est déconnectée lors du traitement, le message passe en failed
les messages planifiés survivent à un redémarrage grâce à BullMQ + Redis

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

Schedule a message

Endpoint

Parameters

Body

Example

Response

Common errors

Important rules

​Endpoint

​Parameters

​Body

​Example

​Response

​Common errors

​Important rules

Endpoint

Parameters

Body

Example

Response

Common errors

Important rules