> ## Documentation Index
> Fetch the complete documentation index at: https://docs.msgflash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Schedule a message

> Schedule a future send in direct mode or with a template.

## Endpoint

```txt theme={null}
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

```bash theme={null}
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](/guides/send-message).

***

## Response

```json theme={null}
{
  "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