---
title: "Create a WhatsApp connect link"
method: POST
path: "/api/v1/channels/connect-sessions"
tags: ["channels"]
---

# Create a WhatsApp connect link

`POST /api/v1/channels/connect-sessions`

## Request

- Base URL: `https://app.blueticked.com`
- URL: `https://app.blueticked.com/api/v1/channels/connect-sessions`
- Auth: HTTP bearer

Mint a single-use link that lets your customer connect their WhatsApp Business account themselves, no Blueticked login required.

Connecting WhatsApp is a human act performed by the business owner in Meta's Embedded Signup; no API key can do it for them. This turns that step into a link you send, instead of asking your customer to create a Blueticked account and find a screen.

The url is returned ONCE and is not stored in plaintext. If you lose it, mint another and let this one expire.

The link is single-use, expires (default 24 hours, 5 minutes to 7 days), and authorises exactly one thing: attaching a WhatsApp channel to this workspace. It cannot read, send, or write anything else.

reference is opaque to us and comes back on the channel.connected webhook, so you can match a completed connect to your own customer record without storing a map of our ids.

redirect_url must be https: your customer's browser follows it after a successful connect.

Pass business_id to say WHOSE channel this becomes. Omit it and the link binds to the workspace default business, which silently collapses every customer onto one. The sends still return 202, from the wrong number.

Subscribe to channel.connected to learn when your customer finished; it fires once per connect. If you would rather poll, GET /api/v1/readiness?business_id=... flips can_send.whatsapp to true for THAT business. Either way, do not ask your customer whether they finished.

## Request body

- object
  - `business_id` string, uuid
  - `expires_in_minutes` number
  - `reference` string
  - `redirect_url` string

## Response `201`

Success

- object
  - `id` string, uuid, required
  - `url` string, required
  - `expires_at` string, date-time, required
  - `business_id` string, uuid, required
  - `reference` string, nullable, required
  - `request_id` string, required

## Other responses

- `400`: Validation failed
- `401`: Unauthorized: missing or invalid API key
- `402`: Insufficient wallet balance
- `403`: Forbidden: scope, plan limit, or suspension
- `404`: Not found
- `409`: Conflict (idempotency-key reuse or resource in use)
- `413`: Request body above the endpoint's size limit
- `422`: Understood but refused: the request is well-formed, the action is not permitted for this resource
- `429`: Rate limited
- `500`: Internal error
- `502`: An upstream provider refused or failed the request
- `503`: Channel or send queue unavailable

---

[API](https://skmtc.dev/blueticked/apis/blueticked-api.md) · [All operations](https://skmtc.dev/blueticked/apis/blueticked-api/llms.txt) · [OpenAPI document](https://skmtc.dev/blueticked/apis/blueticked-api/revisions/07132284f4ff?raw)