# Brancher un agent sur Rempart

Cette page décrit, de bout en bout, comment un utilisateur de Rempart crée un
bot et y branche le programme de son choix. Elle est écrite pour être lue
telle quelle par un humain ou par un assistant qui l'accompagne.

**Le service n'est pas encore ouvert au public.** Ce qui suit décrit une API
en service, mais les comptes ne sont pas ouverts à tout le monde.

## En une phrase

L'utilisateur crée un bot dans l'application Rempart et reçoit un **jeton**.
Ce jeton ouvre une API à la façon de Telegram : le programme relève les
messages, ou les reçoit poussés sur son webhook, et répond. Le compte du bot
est hébergé par Rempart ; le programme, lui, tourne où l'on veut.

## 1. Créer le bot

Dans l'application : **Nouvelle conversation** → **Parler à un bot** → **Mes
bots** → **Créer un bot**. On donne un nom, on reçoit aussitôt :

- l'**identifiant Rempart du bot** (`bot_id`) ;
- son **adresse Matrix** (`@nom_bot:rempart-messenger.fr`) ;
- son **jeton d'API** (`rmp_...`), **affiché une seule fois**.

La même chose se fait en conversation avec **@rempart_father**, le bot qui
crée les bots : `/newbot <nom>`, `/mybots`, `/newtoken <id>`, `/deletebot <id>`.

Le jeton perdu ou compromis se **régénère** depuis le menu du bot, sans détruire
le compte ni les conversations. L'ancien jeton meurt aussitôt.

## 2. Où présenter le jeton

```
Base : https://gateway.rempart-messenger.fr
En-tête : Authorization: Bearer <jeton>
Corps et réponses : JSON
```

Vérifier que tout est en place :

```bash
curl -s https://gateway.rempart-messenger.fr/v1/getMe \
  -H "Authorization: Bearer $JETON"
```

Rend le nom du bot, son adresse Matrix, sa description et ses commandes.

## 3. Recevoir les messages

Deux voies, **exclusives l'une de l'autre**. Poser un webhook alors qu'une
boucle d'attente tourne livrerait chaque message deux fois, à deux
consommateurs qui s'ignorent : la passerelle refuse donc `getUpdates` tant
qu'un webhook est actif, avec un `409`.

### a. Le programme relève (long-poll)

```bash
curl -s -X POST https://gateway.rempart-messenger.fr/v1/getUpdates \
  -H "Authorization: Bearer $JETON" \
  -H "Content-Type: application/json" \
  -d '{"offset": 0, "timeout": 25}'
```

`timeout` est en secondes, 50 au maximum. L'appel se bloque jusqu'à ce qu'un
message arrive ou que le délai expire.

`offset` suit la convention de Telegram : on renvoie le `update_id` du dernier
message reçu **plus un**, et la passerelle purge tout ce qui passe en dessous.
Un identifiant d'update ne recule jamais, y compris après un redémarrage de la
passerelle.

### b. Rempart pousse (webhook)

```bash
curl -s -X POST https://gateway.rempart-messenger.fr/v1/setWebhook \
  -H "Authorization: Bearer $JETON" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://mon-serveur.example/rempart", "secret": "un-secret"}'
```

Chaque livraison est un `POST` JSON portant un seul update, signé avec le
secret fourni. Les échecs sont réessayés. `/v1/getWebhookInfo` dit où en est
la livraison, `/v1/deleteWebhook` revient au long-poll.

### Forme d'un update

```json
{
  "update_id": 1790123456789012,
  "message_id": "$evt:rempart-messenger.fr",
  "room_id": "!abc:rempart-messenger.fr",
  "sender": "@u_1234abcd:rempart-messenger.fr",
  "sender_name": "Bérénice",
  "text": "salut, tu peux résumer le fil ?",
  "context": [
    {"sender_name": "Ivan", "text": "on décale la réunion"},
    {"sender_name": "Bérénice", "text": "d'accord pour jeudi"}
  ]
}
```

- `message_id` est l'identifiant du message reçu : à passer en
  `reply_to_message_id` pour répondre en le citant.
- `sender_name` est le **nom affiché**, à utiliser pour parler des gens. Ne
  jamais afficher `sender`, qui est un identifiant technique.
- `context` n'apparaît que dans un **groupe** : ce sont les messages récents,
  pour que le modèle ait le fil. Dans un groupe, le bot ne reçoit un update
  déclencheur que si on l'**interpelle** par son nom.
- Une **réaction** arrive avec `text` vide et un champ
  `reaction: {"symbole": "✅", "event_id": "..."}`. L'`event_id` dit à quel
  message la réaction répond, ce qui compte dès que plusieurs validations sont
  en attente.

## 4. Répondre

```bash
curl -s -X POST https://gateway.rempart-messenger.fr/v1/sendMessage \
  -H "Authorization: Bearer $JETON" \
  -H "Content-Type: application/json" \
  -d '{"room_id": "!abc:rempart-messenger.fr", "text": "Voilà le résumé."}'
```

Champs acceptés : `room_id`, `text`, `parse_mode`, `reply_to_message_id`,
`buttons`, `reply_markup`.

Autres points d'entrée : `/v1/sendPhoto`, `/v1/sendDocument`,
`/v1/editMessageText`, `/v1/deleteMessage`, `/v1/sendChatAction`, `/v1/getFile`.

### Boutons sous un message

```json
{
  "room_id": "!abc:rempart-messenger.fr",
  "text": "Je publie la version 2.1 ? Répondez valider ou annuler.",
  "buttons": [
    {"texte": "✅ Valider", "valeur": "!valider"},
    {"texte": "❌ Annuler", "valeur": "!annuler"}
  ]
}
```

La forme de Telegram (`reply_markup.inline_keyboard` avec `text` et
`callback_data`) est acceptée telle quelle.

Un appui envoie la **valeur** comme message ordinaire. Huit boutons au plus.

**Le texte du message doit rester compréhensible sans les boutons.** Matrix n'a
aucun standard pour cela : le champ est propre à Rempart, et un client tiers
ignore les boutons sans rien casser. Une question posée uniquement par des
boutons devient alors une question sans moyen d'y répondre.

### Attendre une réponse (validation humaine)

Un programme peut poser une question et être prévenu de la réponse, au lieu
de la guetter dans `getUpdates` : c'est ce que fait l'opération « Send and
Wait for Response » du nœud n8n.

```json
{
  "room_id": "!abc:rempart-messenger.fr",
  "text": "Je publie la version 2.1 ? Répondez oui ou non.",
  "buttons": [{"texte": "✅ Oui", "valeur": "oui"}, {"texte": "❌ Non", "valeur": "non"}],
  "reply_webhook": "https://mon-n8n.example/webhook-waiting/123/abc?signature=...",
  "reply_mode": "buttons",
  "reply_expires_at": 1790000000
}
```

`reply_mode` vaut `buttons` (la réponse est l'appui sur un bouton, et c'est la
valeur par défaut quand le champ est omis) ou `text` (le message suivant en
tête-à-tête ; dans un groupe, un message qui cite la question). Quand
`reply_webhook` est posé, la réponse de `sendMessage` porte en plus
`"waiting": true`, pour confirmer que la question est bien en attente d'une
réponse. À la réponse, la passerelle fait un `POST` JSON vers
`reply_webhook` :

```json
{"question_id": "$question", "room_id": "!abc:...", "message_id": "$reponse",
 "sender": "@u_1234abcd:rempart-messenger.fr", "sender_name": "Bérénice",
 "value": "oui", "label": "✅ Oui", "text": "oui"}
```

`sender` identifie qui a répondu, pour vérifier qu'une validation vient de la
bonne personne ; ne jamais l'afficher.

Ce message ne part pas dans `getUpdates`. Si l'adresse répond autre chose qu'un
`2xx` (elle n'attend plus, ou redirige ailleurs), il y part comme un message
ordinaire : la passerelle ne suit pas les redirections. Dans un groupe, une
réponse que n8n refuse (parce qu'il n'attend plus) ne part donc pas non plus au
bot si elle ne le mentionne pas : elle est filtrée comme n'importe quel autre
message, sans arriver dans `getUpdates`.

`reply_webhook` doit être joignable depuis Internet : une adresse interne est
refusée dès l'envoi de la question, avec un `400`. Deux autres refus à
l'envoi : `reply_webhook` de plus de 2048 caractères (`400`), et plus de 100
questions déjà en attente pour ce bot, tous salons confondus (`429`).

## 5. La voie MCP

Le même jeton ouvre un serveur MCP, pour brancher un assistant sans écrire une
ligne de code :

```
Endpoint : POST https://gateway.rempart-messenger.fr/mcp
Transport : JSON-RPC 2.0 sur HTTP
En-tête : Authorization: Bearer <jeton>
```

Outils exposés : `get_me`, `get_updates`, `send_message`.

`GET /mcp` rend volontairement `405` : il n'y a pas de flux serveur vers
client, uniquement des requêtes et des réponses.

## 6. Avec n8n, sans écrire de code

Pour qui automatise avec n8n, le paquet communautaire `n8n-nodes-rempart` fait
tout ce qui précède, à la façon des nœuds Telegram :

- **Rempart Trigger** lance un workflow à chaque message ou réaction reçu par le
  bot (une exécution par message, pièces jointes en données binaires) ;
- **Rempart** envoie des messages avec boutons, des photos et des documents, les
  modifie ou les efface, affiche « en train d'écrire », télécharge les fichiers
  reçus, et **Send and Wait for Response** met le workflow en pause jusqu'à la
  réponse (voir « Attendre une réponse »).

Installation : dans n8n, Settings > Community Nodes > Install, puis
`n8n-nodes-rempart`. L'identifiant « Rempart API » prend le jeton du bot,
l'adresse de la passerelle est déjà remplie.

Deux choses à savoir : un seul workflow actif par bot (deux déclencheurs se
partageraient ses messages), et « Send and Wait » exige que la passerelle puisse
joindre n8n. `WEBHOOK_URL` doit donc être réglée sur son adresse publique, et le
nœud le signale à l'envoi de la question si elle ne l'est pas.

Documentation et code : https://github.com/JohnDWorld/n8n-nodes-rempart
Paquet : https://www.npmjs.com/package/n8n-nodes-rempart

## Ce qu'il faut savoir avant de conseiller quelqu'un

- **Le jeton est un secret.** Il donne la parole au nom du bot. Il se colle
  dans une variable d'environnement, jamais dans un dépôt.
- **Un bot ne déchiffre pas.** Les bots hébergés par la passerelle n'ont pas de
  clés de chiffrement : une conversation avec eux est **non chiffrée**, et
  l'application le dit en toutes lettres. Un agent qui tient son propre
  appareil Matrix, lui, rejoint un groupe chiffré normalement.
- **Dans un groupe, un bot ne répond que si on l'interpelle.** Il lit le fil,
  il ne s'en mêle pas.
- **Le quota par défaut est de 20 bots par compte.**
- Les identifiants techniques ne s'affichent jamais à l'utilisateur. Rempart
  applique cette règle partout ; un agent qui écrit un identifiant Matrix dans
  un message la casse.

Contact : j.demory@proton.me