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

# Templates

> Manage MsgFlash templates and preview their rendered output with variables.

## Endpoints

| Method   | Endpoint                         |
| -------- | -------------------------------- |
| `GET`    | `/api/v1/templates`              |
| `POST`   | `/api/v1/templates`              |
| `GET`    | `/api/v1/templates/{id}`         |
| `PUT`    | `/api/v1/templates/{id}`         |
| `DELETE` | `/api/v1/templates/{id}`         |
| `POST`   | `/api/v1/templates/{id}/preview` |

Authentication: `x-api-key: <api_key>`

## Parameter models

### `GET /api/v1/templates`

| Parameter | Type    | Required | Location | Description                    |
| --------- | ------- | -------- | -------- | ------------------------------ |
| `page`    | integer | no       | query    | Page, défaut `1`               |
| `limit`   | integer | no       | query    | Taille, défaut `20`, max `100` |

### `POST /api/v1/templates`

| Field      | Type   | Required              | Location | Description                                   |
| ---------- | ------ | --------------------- | -------- | --------------------------------------------- |
| `name`     | string | yes                   | body     | Name of the template                          |
| `type`     | enum   | yes                   | body     | `text`, `image`, `video`, `audio`, `document` |
| `body`     | string | yes if `type=text`    | body     | Body avec placeholders                        |
| `mediaUrl` | string | yes si template media | body     | Public media URL                              |

### `POST /api/v1/templates/{id}/preview`

| Field        | Type   | Required | Location | Description          |
| ------------ | ------ | -------- | -------- | -------------------- |
| `id`         | UUID   | yes      | path     | ID du template       |
| `instanceId` | UUID   | no       | body     | `instance.*` context |
| `contactId`  | UUID   | no       | body     | `contact.*` context  |
| `variables`  | object | no       | body     | `custom.*` values    |

***

## Syntaxe des variables

Format :

```txt theme={null}
{{namespace.variable}}
```

Namespaces supportés :

* `contact.*`
* `user.*`
* `instance.*`
* `custom.*`

Example:

```txt theme={null}
Hello {{contact.firstName}}, votre code {{custom.code}} est prêt sur {{instance.name}}.
```

<Note>
  Variables are automatically detected and recomputed by the backend from `body`. You do not need to maintain the `variables` list manually.
</Note>

***

## Create un template

```bash theme={null}
curl -X POST https://srv.msgflash.com/api/v1/templates \
  -H "x-api-key: msgf_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Relance panier",
    "type": "text",
    "body": "Hello {{contact.firstName}}, utilisez {{custom.code}} aujourd''hui."
  }'
```

Response:

```json theme={null}
{
  "data": {
    "id": "tmpl_uuid",
    "name": "Relance panier",
    "type": "text",
    "body": "Hello {{contact.firstName}}, utilisez {{custom.code}} aujourd'hui.",
    "mediaUrl": null,
    "variables": ["contact.firstName", "custom.code"]
  }
}
```

### Common errors

| Code               | HTTP | When                |
| ------------------ | ---- | ------------------- |
| `VALIDATION_ERROR` | 400  | Invalid body        |
| `TEMPLATE_INVALID` | 400  | Placeholder invalid |

***

## Preview

```bash theme={null}
curl -X POST https://srv.msgflash.com/api/v1/templates/TEMPLATE_ID/preview \
  -H "x-api-key: msgf_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "INSTANCE_UUID",
    "contactId": "CONTACT_UUID",
    "variables": {
      "code": "PROMO10"
    }
  }'
```

```json theme={null}
{
  "data": {
    "rendered": "Hello Awa, utilisez PROMO10 aujourd'hui.",
    "variables": ["contact.firstName", "custom.code"],
    "missingVariables": [],
    "valid": true
  }
}
```

Si une variable ne peut pas être résolue :

* `valid` devient `false`
* `missingVariables` liste les chemins missings

### Common errors

| Code                           | HTTP | When                                |
| ------------------------------ | ---- | ----------------------------------- |
| `NOT_FOUND`                    | 404  | Template not found                  |
| `TEMPLATE_CONTEXT_UNAVAILABLE` | 400  | Missing contact or instance context |

***

## Templates media

Pour `image`, `video`, `audio` ou `document`, le backend exige `mediaUrl`.

Example:

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