> ## 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.

# Message types

> Reference of message types supported by MsgFlash, their fields, and how they are used with templates.

## Overview

| Type         | Description                        | Main required field     |
| ------------ | ---------------------------------- | ----------------------- |
| `text`       | Message texte simple               | `text`                  |
| `image`      | Image avec légende optionnelle     | `mediaUrl`              |
| `video`      | Vidéo avec légende optionnelle     | `mediaUrl`              |
| `audio`      | Fichier audio standard             | `mediaUrl`              |
| `voice_note` | Note vocale WhatsApp               | `mediaUrl`              |
| `document`   | Fichier ou document                | `mediaUrl`              |
| `location`   | Localisation GPS                   | `latitude`, `longitude` |
| `contact`    | Partage d'un contact du répertoire | `contactId`             |

Fields communs :

* `instanceId`
* `to`
* `type` ou `templateId`

<Note>
  Les endpoints `POST /api/v1/messages/send` et `POST /api/v1/messages/schedule` supportent deux modes :

  * mode libre avec `type`
  * mode template avec `templateId`
</Note>

***

## Direct send vs template send

### Direct mode

Vous fournissez directement `type` et les champs associés.

```json theme={null}
{
  "instanceId": "inst_uuid",
  "to": "+33612345678",
  "type": "text",
  "text": "Hello Awa"
}
```

### Template mode

Vous fournissez `templateId` et, si nécessaire, des variables `custom.*`.

```json theme={null}
{
  "instanceId": "inst_uuid",
  "to": "+33612345678",
  "contactId": "cnt_uuid",
  "templateId": "tmpl_uuid",
  "variables": {
    "code": "PROMO10"
  }
}
```

Le backend rend alors le message final avant envoi. Le `type` effectif est celui du template.

***

## text

```json theme={null}
{
  "instanceId": "inst_uuid",
  "to": "+33612345678",
  "type": "text",
  "text": "Hello Jean,\n\nVotre commande #1234 est prête."
}
```

| Field  | Type   | Required | Contraintes         |
| ------ | ------ | -------- | ------------------- |
| `text` | string | ✓        | 1 à 4096 caractères |

***

## image

```json theme={null}
{
  "instanceId": "inst_uuid",
  "to": "+33612345678",
  "type": "image",
  "mediaUrl": "https://cdn.example.com/produit.jpg",
  "text": "Nouvelle collection disponible"
}
```

| Field      | Type   | Required | Contraintes         |
| ---------- | ------ | -------- | ------------------- |
| `mediaUrl` | URL    | ✓        | URL publique        |
| `text`     | string | no       | Légende optionnelle |

***

## video

```json theme={null}
{
  "instanceId": "inst_uuid",
  "to": "+33612345678",
  "type": "video",
  "mediaUrl": "https://cdn.example.com/demo.mp4",
  "text": "Découvrez notre nouveau produit"
}
```

| Field      | Type   | Required | Contraintes         |
| ---------- | ------ | -------- | ------------------- |
| `mediaUrl` | URL    | ✓        | URL publique        |
| `text`     | string | no       | Légende optionnelle |

***

## audio

```json theme={null}
{
  "instanceId": "inst_uuid",
  "to": "+33612345678",
  "type": "audio",
  "mediaUrl": "https://cdn.example.com/message.mp3"
}
```

Affiché comme un fichier audio standard dans WhatsApp.

***

## voice\_note

```json theme={null}
{
  "instanceId": "inst_uuid",
  "to": "+33612345678",
  "type": "voice_note",
  "mediaUrl": "https://cdn.example.com/note.ogg"
}
```

Affiché comme une note vocale WhatsApp.

<Note>
  The difference between `audio` and `voice_note` is mainly how they are displayed in WhatsApp.
</Note>

***

## document

```json theme={null}
{
  "instanceId": "inst_uuid",
  "to": "+33612345678",
  "type": "document",
  "mediaUrl": "https://cdn.example.com/facture.pdf",
  "text": "Facture avril 2026"
}
```

| Field      | Type   | Required | Contraintes      |
| ---------- | ------ | -------- | ---------------- |
| `mediaUrl` | URL    | ✓        | URL publique     |
| `text`     | string | no       | Label or caption |

***

## location

```json theme={null}
{
  "instanceId": "inst_uuid",
  "to": "+33612345678",
  "type": "location",
  "latitude": 6.3654,
  "longitude": 2.4183,
  "locationName": "Boutique Cotonou Centre",
  "locationAddress": "Avenue de la Marina, Cotonou"
}
```

| Field             | Type   | Required | Contraintes        |
| ----------------- | ------ | -------- | ------------------ |
| `latitude`        | number | ✓        | Latitude décimale  |
| `longitude`       | number | ✓        | Longitude décimale |
| `locationName`    | string | no       | Location name      |
| `locationAddress` | string | no       | Address            |

***

## contact

```json theme={null}
{
  "instanceId": "inst_uuid",
  "to": "+33612345678",
  "type": "contact",
  "contactId": "cnt_uuid"
}
```

Le `contactId` doit appartenir à votre compte MsgFlash.

***

## Common fields

| Field         | Type     | Required             | Description                                 |
| ------------- | -------- | -------------------- | ------------------------------------------- |
| `instanceId`  | UUID     | ✓                    | Instance WhatsApp à utiliser                |
| `to`          | string   | ✓                    | E.164 number                                |
| `type`        | enum     | ✓ if no `templateId` | Direct message type                         |
| `templateId`  | UUID     | ✓ if no `type`       | MsgFlash template to use                    |
| `contactId`   | UUID     | no                   | Source contact or template context          |
| `variables`   | object   | no                   | Valeurs pour `custom.*`                     |
| `scheduledAt` | ISO 8601 | no                   | Utilisé uniquement sur `/messages/schedule` |

***

## Media templates

Un template peut être de type :

* `text`
* `image`
* `video`
* `audio`
* `document`

Pour un template media, `mediaUrl` est obligatoire sur le template lui-même.

Example:

```json theme={null}
{
  "name": "Brochure PDF",
  "type": "document",
  "body": "Hello {{contact.firstName}}, voici votre brochure.",
  "mediaUrl": "https://cdn.example.com/brochure.pdf"
}
```