> ## Documentation Index > Fetch the complete documentation index at: https://docs.linkiasoft.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a connect link > Returns a one-time `connectUrl` to open in a popup from your frontend. The popup runs the provider sign-in and reports the result back to your window (at `origin`) or to your `redirectUri`. The channel is created in the workspace that owns the API key. The link works **once** and expires after **30 minutes**. Create a new session for every attempt, and never log the URL — it is a credential. Requires `channels:manage`. ## OpenAPI ````yaml /openapi/public-api.yaml post /v1/connect-sessions openapi: 3.1.0 info: title: Linkiasoft API version: 1.0.0 description: > Send and read messages across WhatsApp, Instagram, Messenger and Telegram, and read and update the CRM behind them — leads, pipeline stages, company contacts and activity history. Every endpoint is authenticated with a tenant-scoped API key and returns only data belonging to that key's workspace. **Two hosts, one key.** Messaging lives on `social.linkiasoft.com` and the CRM on `api.linkiasoft.com`. Each endpoint below shows its own base URL; the same API key authenticates against both. servers: - url: https://social.linkiasoft.com/api description: Production security: - apiKey: [] tenantId: [] tags: - name: Conversations description: Read threads and send messages. - name: Templates description: Approved WhatsApp message templates. - name: Channels description: The connected accounts you can send from. - name: Connect sessions description: > Let your users connect WhatsApp, Messenger, Instagram or TikTok from inside your own product, through a sign-in popup we host. See the Channel connect guide. - name: Leads description: Deals moving through your pipeline. - name: Pipeline description: The stages a lead can sit in. - name: Contacts description: People attached to a company. - name: Activities description: Logged calls, emails, meetings and follow-ups. - name: Customers description: The companies and accounts your contacts belong to. - name: Tags description: Labels applied to customers, contacts and leads. - name: Quick replies description: Team-shared canned responses. - name: WhatsApp groups description: Create and manage WhatsApp group chats. paths: /v1/connect-sessions: post: tags: - Connect sessions summary: Create a connect link description: > Returns a one-time `connectUrl` to open in a popup from your frontend. The popup runs the provider sign-in and reports the result back to your window (at `origin`) or to your `redirectUri`. The channel is created in the workspace that owns the API key. The link works **once** and expires after **30 minutes**. Create a new session for every attempt, and never log the URL — it is a credential. Requires `channels:manage`. operationId: createConnectSession requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConnectSessionInput' examples: whatsapp: summary: WhatsApp, reporting back to an opener window value: platform: whatsapp origin: https://app.example.com state: user-4821 responses: '201': description: The session, with the link to open. content: application/json: schema: allOf: - $ref: '#/components/schemas/ConnectSession' - type: object required: - connectUrl properties: connectUrl: type: string format: uri description: >- Open this in a popup. The token is in the fragment, so it never reaches a server log. examples: - https://crm.linkiasoft.com/connect#token=cst_... '400': description: > `origin` or `redirectUri` is not an `https` URL (plain `http` is accepted only for `localhost`), `origin` has a path, or `platform` is unknown. content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '403': description: > The key lacks `channels:manage`, or the workspace is not enabled for the direct Meta connection for this channel type. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: ConnectSessionInput: type: object required: - platform properties: platform: type: string enum: - whatsapp - whatsapp_qr - facebook - instagram - tiktok description: > Which channel the popup connects. `facebook` is Messenger. `whatsapp_qr` links a number as a WhatsApp Web linked device, by QR scan or pairing code. channelName: type: string maxLength: 100 description: > `whatsapp_qr` only: the channel's display name. Defaults to the linked number, e.g. `+201001234567`. origin: type: string format: uri description: > Origin of the window that opens the popup, e.g. `https://app.example.com`. The result is sent with `postMessage` to `window.opener` at exactly this origin. redirectUri: type: string format: uri description: > Where the popup goes when there is no opener window to notify. Receives `?sessionId=…&status=…&channelId=…&state=…`. state: type: string maxLength: 512 description: Your own reference, echoed back in every result. Never interpreted. locale: type: string enum: - en - ar default: en description: Language of the hosted page. ConnectSession: type: object properties: id: type: string format: uuid platform: type: string enum: - whatsapp - whatsapp_qr - facebook - instagram - tiktok status: type: string enum: - pending - connected - cancelled - expired description: > `expired` means the 30-minute link ran out before the person finished. channelId: type: - string - 'null' format: uuid description: >- Set once `status` is `connected`. Use it as `channelId` elsewhere in this API. channelName: type: - string - 'null' state: type: - string - 'null' description: The `state` you sent, unchanged. createdAt: type: string format: date-time expiresAt: type: string format: date-time description: When the link stops working. completedAt: type: - string - 'null' format: date-time Error: type: object properties: statusCode: type: integer message: description: A sentence explaining the failure, or a list of field errors. oneOf: - type: string - type: array items: type: string error: type: string examples: - statusCode: 403 message: 'API key missing required scope(s): conversations:read' error: Forbidden responses: Unauthorized: description: The API key is missing, invalid, revoked, or expired. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: > Your workspace API key. Create one in **Settings → API Keys**; the plaintext value is shown once and never again. Keys are scoped. A key needs `conversations:send` to send, `conversations:read` to read threads and messages, `templates:read` to list templates, `channels:read` to list channels, and `channels:manage` to create connect sessions. A key missing the scope for an endpoint gets `403`. The CRM endpoints use the same `resource:action` form: `leads:read`, `leads:create`, `leads:update`, `leads:delete`, `customers:read`, `customers:create`, `customers:update`, `customers:delete`, `customers:manage`. Several resources have no scope of their own and borrow one: | Resource | Governed by | |---|---| | Contacts | `customers:*` | | Activities | `customers:*` for customer activities, `leads:*` for lead activities | | Tags | `customers:read` to list, `customers:manage` to change | | Pipeline stages | `leads:*` | | Quick replies | `quick-replies:read` / `quick-replies:write` | | WhatsApp groups | `wa-groups:manage` | Grant only what the integration needs — a key that only sends notifications should hold `conversations:send` and nothing else. tenantId: type: apiKey in: header name: X-Tenant-Id description: > Your workspace UUID. Required on every request **in addition to** `x-api-key`. It does not select the workspace — data access is always scoped to the workspace that owns the API key, and a mismatched value cannot read anyone else's data. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.