Migrer de 2.1 vers v3
Pour une intégration qui tourne déjà sur la 2.1, cette page associe chaque opération à son équivalent v3, signale ce qui change de forme en chemin et indique clairement ce qui ne suit pas.
retarget et les webhooks n’ont pas d’équivalent en v3
Deux opérations dont vous dépendez peut-être en 2.1 n’existent pas aujourd’hui en v3 : retarget et l’envoi de webhooks (messageUnlockEvent). Lisez ceci avant de parcourir la correspondance ci-dessous.
Opération par opération
Tout le reste de la 2.1 a un équivalent en v3.
| Opération 2.1 | Équivalent v3 |
|---|---|
| redirect | POST /containers, puis GET /containers/{crid}/url |
| notify | POST /containers/{crid}/notify |
| modify | PATCH /containers/{crid} |
| details | GET /containers/{crid} |
| qrcode | GET /containers/{crid}/qrcode |
| card | GET /containers/{crid}/card |
| redirect (user) | GET /containers/{crid}/redirect |
- API v3 : Conteneurs
- redirect, notify, modify, details, qrcode et card se retrouvent tous sous /containers.
- API v3 : Messages
- L’accès direct aux messages, qui n’a aucun équivalent en 2.1.
- Référence API 2.1
- La référence complète de la 2.1, pour les noms d’opérations de la colonne de gauche ci-dessus.
- API v3 : Erreurs
- L’enveloppe d’erreur v3 présentée ci-dessous, dans son intégralité.
Ce qui change de forme
Au-delà des chemins eux-mêmes, trois choses changent de forme entre les deux API.
- La clé quitte le chemin de l’URL pour devenir un jeton Bearer dans l’en-tête Authorization.
- L’enveloppe d’erreur change entièrement — pas des champs renommés, une autre structure.
- Les URL ne passent plus par un unique champ url à la destination ambiguë — la v3 renvoie explicitement recordingUrl et previewUrl.
json
// 2.1
{ "status": 1, "error": "crid_unknown" }
json
// v3
{ "error": { "code": "NOT_FOUND", "message": "..." } }Ce que vous y gagnez
Passer à la v3 ne consiste pas seulement à retrouver ce que faisait déjà la 2.1 — vous gagnez aussi des fonctionnalités que la 2.1 n’a jamais eues.
- Accès aux messages — lister et lire les messages, et mettre à jour leurs données, sans avoir à résoudre tout le conteneur.
- Pagination — lister conteneurs et messages avec limit, skip et order, au lieu de résoudre un crid à la fois.
- Mode galerie — un conteneur qui accepte plusieurs messages.
- unlock distinct de notify — décider du moment où un message devient accessible au destinataire, indépendamment du moment où l’envoi est déclenché.
- Des contacts expéditeur et destinataire typés, avec un choix de canal explicite.