Conversion links
# Conversion links
OWNER or DELEGATEE needs MANAGE_CONVERSION_LINKS for the exact selected channel. Marketing-tools permission alone does not suffice. Source account resources exclude the three tools and conversion-link recovery; no domain prerequisite is added. Creation requires a verified eligible source plan; existing-link reads/editing/cleanup are not gated by creation eligibility. See the [exact policy](../tools/publ_conversion_link_apply.md#creation-policy). Missing/unknown plans fail closed and the person receives the human plan destination, without a purchase or billing call.
| Need | Tool |
| --- | --- |
| List/read a link or its connected segments/promotions | [conversion_links_get](../tools/publ_conversion_links_get.md) |
| Compose creation or edit sharing metadata/thumbnail | [conversion_link_apply](../tools/publ_conversion_link_apply.md) |
| Activate/deactivate or delete selected links | [conversion_links_manage](../tools/publ_conversion_links_manage.md) |
## Read and plan
Read a bounded list and use its creationRevision only for create. For update/visibility/delete, read each selected numeric id in detail and use its revision; a list row or keyword is not a revision.
```json
{
"channelCode": "selected-channel-code",
"view": {
"kind": "list",
"page": 1,
"limit": 15
}
}
```
The create workflow combines source wizard fields. This sample is a dry run; replace its zero digest with the returned creationRevision. dryRun defaults to false when omitted.
```json
{
"channelCode": "selected-channel-code",
"requestId": "conversion-guide-01",
"action": "create",
"expectedRevision": "0000000000000000000000000000000000000000000000000000000000000000",
"settings": {
"name": "Welcome link",
"title": "Welcome to our channel",
"description": "Read our latest updates.",
"destination": {
"kind": "WEB",
"url": "https://example.com/welcome"
}
},
"dryRun": true
}
```
After inspecting the plan, apply the intended operation and retain the requestId and original input. UTM defaults to direct / (none) with empty campaign/content/term. A keyword is server-generated. Creation normalizes only canonical numeric receipt id/channelId while preserving a nonempty opaque auto-created segment identity. Old unknown-ID tasks are not repaired or adopted by this correction. Creation may additionally create a segment; returned segment metadata does not verify its contents or authorize automatic campaign creation. Destination/UTM/keyword cannot be edited afterward through this workflow. Update supports name, sharing title/description and original thumbnail only.
Original PNG/JPEG thumbnails must be below 10,000,000 decimal bytes. Omission preserves an existing image; null removal and replacement URLs are unsupported. Upload needs configured resource gateway/bucket/region. Only verified original-byte receipts enter the save; separate upload/save effects have no rollback or object cleanup.
## Continue a task
Use taskType conversion-link with the returned taskId:
```json
{
"taskId": "conversion-guide-01",
"taskType": "conversion-link"
}
```
Status reads history. Resume may continue untouched stages after context/content checks. Sent create/update/activation/delete/grant/upload requests never repeat. Known-ID writes can reconcile by readback; a create missing its durable returned ID cannot be adopted by name. Uncertain image stages require inspection, while an unstarted upload requires the original apply bytes after restart. See the [phase contract](../tools/publ_conversion_link_apply.md#results-and-task-recovery).
For visibility, unchanged targets are omitted from the effect but included in verification. One or many changed IDs use bulk activation with200/204 acknowledgement; deletion always uses bulk-delete with200/204 acknowledgement. Cross-save matching tolerates generated updatedAt only; revisions and pre-write conflict checks retain it. Deletion requires DELETE_CONVERSION_LINKS and should first be planned; success needs recognized404 detail checks plus a stable full inventory scan bounded to 5,000 links.
## Share URL configuration
The host supplies conversionLinkBaseUrl in runtime service configuration or PUBL_CONVERSION_LINK_BASE_URL. Use the actual environment's HTTPS base ending in /, without credentials, query or fragment. It is separate from API and console origins and is not silently inherited across a custom API override. The returned keyword is validated and encoded as one path component. With no configured base, shareUrl is null; console navigation still works. Never guess a production hostname from an ID or another origin.
A generated share URL proves neither redirect behavior nor attribution. Destination/share/image URLs are never fetched by these tools. Detail/editor navigation uses the selected channel/id; connected tabs use their own console child paths. Demo produces no live share/navigation link.
## Connected views and limits
segments reads one source-filtered page for the chosen link, defaulting to100 rows rather than the ordinary list default15. Both accept explicit15/30/50/100. It performs no condition-tree editing or member export. promotions exposes a restricted connected-benefit/campaign projection. Its source request is unpaged even though the UI has controls, so the bridge exposes source pagination and moreReported with nextPage:null rather than inventing a complete export. No financial mutation is part of these tools.
Fresh readback confirms stored fields within its stated scope; completed task history is confirmed:false.
Current read results include their selected view and retain list/segment page, size and supported filters in the single console link. Open that returned address for the same selection. CONVERSION_PAGE_OUT_OF_RANGE means the selected page is past the observed total; explicitly request page1 again. It is not a successful empty inventory, and the bridge does not choose a replacement page. The source-unpaged promotion tab remains unchanged.
