Skip to main content

Channel Connect Links

A channel connect link is a secure, time-limited URL you generate and send to a customer. They open it, authenticate with the provider (e.g. Meta for WhatsApp), and the connected channel lands in the tenant you designate — without the customer ever seeing your dashboard or credentials.

This is the self-serve onboarding primitive for platform partners: instead of collecting a customer's WhatsApp/Telegram credentials yourself, you hand them a link.

Where the channel lands​

The channel created through a connect link belongs to the tenant that issued the token. Combine this with X-Tenant-ID to place a customer's channel directly into their sub-account:

Parent token + X-Tenant-ID: tenant_acme_123
      │
      └─ POST /channel-connect-tokens   → link onboards the channel INTO tenant_acme_123
POST /api/v1/channel-connect-tokens

Requires the channels:create scope. To create the link for a sub-account, add the X-Tenant-ID header (see Cross-Account API Access).

Request body​

FieldTypeRequiredDescription
allowed_channel_typesarrayYesWhich channel types the link may connect. Any of: telegram, whatsapp, instagram, messenger, gmail, smtp_imap, sendgrid_byok, mailgun_byok, sendgrid_managed, sms.
allowed_channel_modesobjectNoOptional per-channel restriction on which connect mode the link may use. See Restrict connect modes. Omit it (or a given channel's key) to allow every mode for that channel.
namestringNoInternal label for the token (e.g. "Acme Corp Setup").
expires_in_hoursintegerNoValidity window in hours (1–168, default 24).
max_usesintegerNoMaximum successful connections (1–100, default 10). Set to 1 for a single customer.
use_window_minutesintegerNoGrace period in minutes after first use (5–1440, default 30).
partner_namestringNoYour brand/company name shown on the connect page (white-label).
partner_redirect_urlstringNoURL to send the customer to after a successful connection.

curl​

curl -X POST "https://api.sendseven.com/api/v1/channel-connect-tokens" \
  -H "Authorization: Bearer s7_api_PARENT_TOKEN" \
  -H "X-Tenant-ID: tenant_acme_123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp WhatsApp Setup",
    "allowed_channel_types": ["whatsapp"],
    "expires_in_hours": 48,
    "max_uses": 1,
    "partner_name": "Your Platform",
    "partner_redirect_url": "https://yourapp.com/onboarding/done"
  }'

Response (201 Created)​

{
  "id": "cct_9a8b7c6d",
  "token_prefix": "s7_cc_a1",
  "connect_url": "https://app.sendseven.com/connect/s7_cc_a1b2c3d4e5f6g7h8...",
  "allowed_channel_types": ["whatsapp"],
  "partner_name": "Your Platform",
  "expires_at": "2026-03-06T09:00:00Z",
  "max_uses": 1,
  "uses_count": 0,
  "created_at": "2026-03-04T09:00:00Z"
}

Send the connect_url to your customer. The raw token is embedded in that URL and is shown only once — persist the connect_url if you need to resend it.

Restrict connect modes​

Some channels can be connected in more than one way. allowed_channel_modes lets a link pin the exact mode(s) a customer may pick — for example, force a WhatsApp link to the standard API onboarding and hide Coexistence, or offer only messaging (no social/comments) for Facebook and Instagram.

It is an object keyed by channel type, each mapping to a list of allowed modes:

ChannelModes
instagrammessaging, social
messengerbusiness_messaging, business_social, personal_social
whatsappclassic, coexistence
{
  "allowed_channel_types": ["whatsapp", "instagram"],
  "allowed_channel_modes": {
    "whatsapp": ["classic"],
    "instagram": ["messaging"]
  }
}

Rules:

  • Absent = all allowed. If allowed_channel_modes is omitted entirely, or a given channel's key is absent, every mode for that channel is allowed. Links created before this field existed keep working exactly as before.
  • List at least one mode per channel. A channel key must name one or more modes. To allow all modes, omit the key rather than passing an empty list — an empty list is rejected (422).
  • Unknown channels or modes are rejected (422).
  • Enforcement is the intersection of the link's modes and your account's feature availability, and it fails closed. A mode is offered to the customer, and accepted server-side, only when the link permits it and the feature is enabled for the issuing account. Restricting a link can therefore only ever narrow what is offered — it never unlocks a mode the account doesn't have. Requesting a mode the link forbids returns a 4xx error.

The public connect page reads the effective (already-intersected) mode list, so customers only ever see the modes they can actually complete.

The customer's experience​

  1. The customer opens connect_url.
  2. They see a branded connect page (using partner_name) scoped to the allowed_channel_types.
  3. They authenticate with the provider (e.g. Meta login for WhatsApp, bot token for Telegram, mailbox credentials for email).
  4. On success, the channel is created in the target tenant, and — if set — they're redirected to partner_redirect_url.

Know the moment a channel connects​

Rather than polling, subscribe to the channel.created webhook event. When a customer completes a connect link, you receive an event whose data.channel.created_via_connect_token_id matches the token you issued — so you can correlate the connection back to the exact customer and link:

{
  "type": "channel.created",
  "tenant_id": "tenant_acme_123",
  "data": {
    "channel": {
      "id": "ch_new",
      "platform": "whatsapp",
      "status": "connected",
      "created_via_connect_token_id": "cct_9a8b7c6d"
    }
  }
}

Pair this with channel.updated to be alerted if that channel later disconnects (e.g. the customer's token is revoked), so you can prompt them to reconnect.

Manage connect tokens​

ActionEndpoint
List tokensGET /api/v1/channel-connect-tokens
Get oneGET /api/v1/channel-connect-tokens/{id}
RevokeDELETE /api/v1/channel-connect-tokens/{id} (or the revoke endpoint)

Revoking a token immediately invalidates its link; connections already completed are unaffected.

SMS availability

sms in allowed_channel_types is gated per-account until SMS is enabled for the issuing tenant. If SMS isn't enabled, the request is rejected with guidance.

Next steps​