Migrating from 2.1 to v3
For an integration already running on 2.1, this page maps each operation to its v3 equivalent, points out what changes shape along the way, and states plainly what does not carry over.
retarget and webhooks have no v3 equivalent
Two operations you may depend on in 2.1 are not in v3 today: retarget and webhook delivery (messageUnlockEvent). Read this before working through the mapping below.
Operation by operation
Everything else in 2.1 has a v3 equivalent.
| 2.1 operation | v3 equivalent |
|---|---|
| redirect | POST /containers, then 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 |
| user redirect | GET /containers/{crid}/redirect |
- API v3: Containers
- redirect, notify, modify, details, qrcode, and card all live under /containers.
- API v3: Messages
- The direct message access that has no 2.1 equivalent at all.
- API 2.1 reference
- The full 2.1 reference, for the operation names in the left column above.
- API v3: Errors
- The v3 error envelope shown below, in full.
What changes shape
Beyond the paths themselves, three things change form between the two APIs.
- The key moves from the URL path to a Bearer token in the Authorization header.
- The error envelope changes entirely — not renamed fields, a different shape.
- URLs are no longer one url field whose destination is ambiguous — v3 returns recordingUrl and previewUrl explicitly.
json
// 2.1
{ "status": 1, "error": "crid_unknown" }
json
// v3
{ "error": { "code": "NOT_FOUND", "message": "..." } }What you gain
Moving to v3 is not only about matching what 2.1 already did — it also adds capabilities 2.1 never had.
- Message access — list and read messages, and update message data, independently of resolving the whole container.
- Pagination — list containers and messages with limit, skip, and order, instead of resolving one crid at a time.
- Gallery mode — a container that accepts more than one message.
- unlock kept separate from notify — decide when a message becomes accessible to the recipient independently of when delivery is triggered.
- Typed sender and recipient contacts, with an explicit channel choice.