Link a channel

POST/v1/channels

Links an Apple Messages for Business business to your brand.

Behavior

Repeating a link you already hold returns HTTP 200 already_linked; idempotent, never an error.
Never re-points an existing binding: each collision returns a distinct HTTP 409 naming the conflict (brand_occupied, cross_brand_conflict).
Unlinking is not available through this API; contact us.

Body ParametersJSONExpand Collapse

business_id: string

The business id to link, as a UUID. Anything else is 400 business_id_invalid.

channel: "amb"

Must be amb; any other value is 400 channel_unsupported.

claim_token: optional string

The claim token authorising this link, issued to you by Linq for this specific business. Required to CREATE a link: without it the call is 400 claim_required, and a token that does not match this brand and this business is 403 claim_invalid.

Optional rather than required because re-posting a link your brand already holds answers 200 already_linked and needs no token. A claim is single-use, so a replay has none left to send. Omit it in that case.

Every rejection is the same claim_invalid regardless of why (unknown, expired, already used, withdrawn, or issued for a different business), so the endpoint cannot be used to discover which businesses exist or who holds them.

ReturnsExpand Collapse

ChannelLinkResponse object { channel, outcome }

A decided link. outcome says whether this call created it.

channel: ChannelBinding { business_id, channel, created_at, 2 more }

One linked channel identity: the Apple Messages for Business business this brand receives from and sends as.

business_id: string

The linked business id: a UUID issued at business registration.

channel: "amb"

The messaging channel. amb is the only channel this API serves today.

created_at: string

formatdate-time

entry_point_url: string

The Messages entry deep link for this binding (https://bcrw.apple.com/urn:biz:<business_id>); open it from an approved tester device to start a chat with the business and verify the link end to end. DERIVED from business_id, not stored: the URL format is platform knowledge, served here so no client composes it by hand.

origin: "seed" or "connect" or "control"

Where the link came from: connect is a self-service link (the Connect landing page, or POST /v1/channels: the same self-service path over this API), seed is boot configuration, control was provisioned by Linq. Provenance only; all three behave identically.

One of the following:

"seed"

"connect"

"control"

outcome: "linked" or "already_linked"

linked (status 201); this call created the binding. already_linked (status 200): your brand already held exactly this binding; nothing changed and nothing is wrong. The two conflicts are errors, not outcomes: 409 brand_occupied (your brand already holds a DIFFERENT business id on the channel) and 409 cross_brand_conflict (the business id is held by another brand). A link is never re-pointed by this endpoint.

One of the following:

"linked"

"already_linked"

Link a channel

curl https://messages.api.linqapp.com/v1/channels \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $LINQ_AMB_API_KEY" \
    -d '{
          "business_id": "a884eddf-b0ad-4be4-9c0e-071531638768",
          "channel": "amb"
        }'

{
  "outcome": "linked",
  "channel": {
    "channel": "amb",
    "business_id": "a884eddf-b0ad-4be4-9c0e-071531638768",
    "origin": "connect",
    "entry_point_url": "https://bcrw.apple.com/urn:biz:a884eddf-b0ad-4be4-9c0e-071531638768",
    "created_at": "2026-08-01T12:00:00Z"
  }
}

Returns Examples

{
  "outcome": "linked",
  "channel": {
    "channel": "amb",
    "business_id": "a884eddf-b0ad-4be4-9c0e-071531638768",
    "origin": "connect",
    "entry_point_url": "https://bcrw.apple.com/urn:biz:a884eddf-b0ad-4be4-9c0e-071531638768",
    "created_at": "2026-08-01T12:00:00Z"
  }
}