Messages et jetons

Un message est la vidéo enregistrée pour un achat ou une contribution. Vous le nommez avec un mrid de votre choix. Votre serveur émet un jeton de courte durée pour ce mrid, et le widget utilise ce jeton à la place d’une clé d’édition ou d’un lien destinataire. Votre serveur ne transmet jamais de clé secrète au navigateur.

Avant de lire cette page

Lisez d’abord la référence des conteneurs : un message appartient toujours à un conteneur, et le mode du conteneur détermine combien de messages il peut contenir. Conteneurs et messages

Le mrid

Le mrid est votre identifiant pour un message : une ligne de commande, une contribution, un don. Il compte de 1 à 64 caractères parmi les lettres, les chiffres, le deux-points, le tiret bas et le tiret. Il est unique au sein d’un conteneur. Un jeton émis pour un mrid qui n’existe pas encore crée ce message quand le widget l’enregistre.

Ce qu’un message expose

Un message lu via la v3.1 renvoie des champs différents selon le réglage messageAccess de votre plateforme. Livstick fixe cette valeur ; votre clé ne peut pas la modifier. Le tableau liste les champs par niveau.

Champs d’un message selon messageAccess
Champ	confidential	admin
messageId, mrid, role, state, held, durationMs, revision	Oui	Oui
createdAt, updatedAt, releasedAt, viewedAt	Oui	Oui
thumbnailUrl, videoUrl (messages publiés uniquement)	Non	Oui
data: firstname, lastname, relation; content	Non	Oui
Coordonnées, IP de l’expéditeur, scoring, état de modération, clé d’édition	Jamais	Jamais

États d’un message

Le champ state indique où en est un message. N’affichez que les messages published à un public.

États d’un message
État	Signification
processing	Enregistré, pas encore encodé.
held	Encodé et retenu jusqu’à ce que vous le libériez (paiement pas encore confirmé).
pending_review	En attente de la décision d’un modérateur.
published	Visible par son public.
hidden	Masqué par un modérateur. Il peut réapparaître.
rejected	Rejeté par la modération. Il ne peut pas être supprimé via l’API.
failed	L’encodage a échoué.

Jetons d’enregistrement

Un jeton d’enregistrement permet au widget d’enregistrer un message pour un mrid, dans un conteneur. Votre serveur le demande, puis le transmet au navigateur dans la propriété recordToken du widget.

POST /containers/{crid}/record-tokens

curl https://<client-api-host>/api/v3.1/containers/AUB-20481/record-tokens \
  -H "Authorization: Bearer liv_<prefix>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{"mrid": "DON-51873", "role": "contributor", "hold": true, "expiresIn": 3600}'

role vaut organizer ou contributor. Un conteneur single n’accepte que organizer, et une demande contributor est refusée avec 409 MODE_MISMATCH.
hold vaut false par défaut. Avec hold à true, le message est encodé puis retenu jusqu’à ce que vous appeliez release. Tant qu’il est retenu, il n’est listé nulle part et aucun e-mail n’est envoyé aux autres participants.
expiresIn est compris entre 60 et 86400 secondes. La valeur par défaut est 3600.
sender.firstName et sender.lastName sont facultatifs et servent à pré-remplir le widget.
Demander un jeton pour une galerie fermée renvoie 409 GALLERY_CLOSED.

Mise en attente et libération pour les cagnottes et l’e-commerce

Utilisez hold quand la vidéo ne doit pas être visible avant la confirmation d’un paiement. Le parcours compte trois étapes, et l’ordre des appels vous appartient.

Émettez un jeton d’enregistrement avec hold à true et laissez le widget enregistrer. Le widget signale message.held ; rien n’est listé et rien n’est envoyé aux autres.
Quand le paiement est confirmé de votre côté, appelez POST /containers/{crid}/messages/{mrid}/release. L’appel est idempotent : un message déjà libéré renvoie 200 sans modification.
Le message devient visible, et Livstick envoie message.ready, ainsi que gallery.message_added pour une contribution à une galerie.

Jetons de visualisation

Un jeton de visualisation permet au widget de récupérer les messages et de les lire. C’est la seule autorisation dont une page publique a besoin, et il n’accorde que la lecture : ni réaction, ni marque de visionnage. Les réactions demandent toujours l’urid du destinataire.

POST /containers/{crid}/view-tokens

curl https://<client-api-host>/api/v3.1/containers/AUB-20481/view-tokens \
  -H "Authorization: Bearer liv_<prefix>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{"scope": "viewer", "mrid": "DON-51873", "expiresIn": 900}'

scope vaut viewer ou owner. Un jeton owner permet aussi au widget d’afficher le mrid de chaque message et le contexte que vous lui transmettez ; utilisez-le dans votre back-office, pas sur une page publique.
mrid est facultatif. Sans lui, le jeton lit tous les messages listés du conteneur. Avec lui, le jeton ne lit que ce message, et le mrid doit exister (sinon 404 MESSAGE_NOT_FOUND).
expiresIn est compris entre 60 et 3600 secondes. La valeur par défaut est 900.
La réponse ne contient pas l’urid. La page qui reçoit le jeton n’en a pas besoin.

Supprimer un message

DELETE /containers/{crid}/messages/{mrid} supprime un message en cas de remboursement ou de rétractation. L’appel renvoie 204. L’auteur ne reçoit aucun e-mail : le webhook message.deleted prévient votre système, qui décide s’il faut lui écrire.

Le message principal d’une galerie ne peut pas être supprimé tant que d’autres messages y restent : 409 GALLERY_NOT_EMPTY.
Un message rejeté par la modération ne peut pas être supprimé via l’API : 409 MESSAGE_REJECTED.
La raison indiquée dans le webhook est client pour un appel effectué avec votre clé.

Lister les messages

GET /containers/{crid}/messages liste les messages d’un conteneur, le message principal en premier, puis dans l’ordre d’enregistrement. Filtrez avec mrid pour un message, ou avec state pour un état du tableau ci-dessus. La taille de page va de 1 à 200, 50 par défaut.