# Connect Channel ### Endpoint **POST** `https://app.marketingblocks.ai/api/v1/social-sparks/connect-channel` This endpoint initiates a social media channel connection flow for a user. It generates a secure `connect_url` that the user must open in a browser to select and connect one or more social platforms (Facebook, Instagram, Twitter/X, LinkedIn, YouTube, TikTok, etc.) through OAuth authorization. It supports: * Web applications * Mobile applications (iOS / Android) * AI agents / CLI tools MarketingBlocks hosts the social OAuth flow and returns a connected `channel_id` or `channel_ids`. After the connection is completed successfully: * web and mobile clients may receive a redirect to `redirectUrl` * AI agents / CLI tools may poll connection status using `connect_token` This endpoint is typically used before publishing posts, retrieving analytics, fetching posts, or performing any social channel operations. Requires the `add-channels` permission. *** ### Authentication **Type:** Bearer Token ```http Authorization: Bearer ``` *** ### Request Body Parameters | Parameter | Type | Required | Description | | ------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `userId` | string | Yes | External identifier for the user in your application. This value is used to associate connected social channels with your user account. | | `redirectUrl` | string | No | URL or deep link where the user should be redirected after completing the OAuth flow. Required for web/mobile redirect-based flows. Optional for AI agents or CLI tools using polling. | *** ### Example Request #### Web / Mobile ```bash curl --location 'https://app.marketingblocks.ai/api/v1/social-sparks/connect-channel' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "userId": "external-user-123", "redirectUrl": "https://client.example.com/callback" }' ``` #### AI Agent / CLI ```bash curl --location 'https://app.marketingblocks.ai/api/v1/social-sparks/connect-channel' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "userId": "external-user-123" }' ``` *** #### Plain Request ```http POST https://app.marketingblocks.ai/api/v1/social-sparks/connect-channel Content-Type: application/json Authorization: Bearer { "userId": "external-user-123", "redirectUrl": "https://client.example.com/callback" } ``` *** ### Response Structure The response is a JSON object with the following keys: | Key | Type | Description | | --------------- | ------- | -------------------------------------------------------------------------------------------------- | | `status` | boolean | Indicates whether the request was successful. | | `connect_url` | string | Secure URL that the user must open in a browser to complete the social channel connection process. | | `connect_token` | string | Temporary connection session token. Can be used to validate or poll connection status. | | `expires_in` | integer | Time in seconds before the connection session expires. | *** ### Connect Flow 1. Your application calls the `connect-channel` endpoint. 2. The API returns a `connect_url`. 3. Redirect the user or open the `connect_url` in a browser/webview. 4. The user selects the social platform(s) they want to connect. 5. The user completes the OAuth authorization process with the selected platform. 6. After successful authorization, the user is redirected to the provided `redirectUrl`. *** ### Example Response ```json { "status": true, "connect_url": "https://app.marketingblocks.ai/connect/channels?connect_token=abc123", "connect_token": "abc123", "expires_in": 900 } ``` *** ### Connect Flow #### Web App Flow 1. Your application calls the `connect-channel` endpoint. 2. The API returns `connect_url`, `connect_token`, and `expires_in`. 3. Redirect the user to `connect_url` in a browser. 4. The user selects a social platform and completes OAuth. 5. After success, the user is redirected to your `redirectUrl`. 6. Your application reads: * `channel_id` or `channel_ids` * `platform` * `status` * `connect_token` #### Mobile App Flow 1. Your mobile app calls the `connect-channel` endpoint. 2. The API returns `connect_url`, `connect_token`, and `expires_in`. 3. Open `connect_url` in a browser or webview. 4. The user completes the hosted OAuth flow. 5. MarketingBlocks redirects back to your mobile deep link or universal link. 6. Your mobile app reads: * `channel_id` or `channel_ids` * `platform` * `status` * `connect_token` 7. If the redirect is not handled reliably, the app may poll the connection status using `connect_token`. #### AI Agent / CLI Flow 1. Your agent calls the `connect-channel` endpoint. 2. The API returns `connect_url`, `connect_token`, and `expires_in`. 3. The agent opens or shows `connect_url` to the user. 4. The user completes the hosted OAuth flow in the browser. 5. The agent polls the connection status endpoint using `connect_token`. 6. When the status becomes `success`, the agent reads: * `channel_id` or `channel_ids` * `platform` *** ### Mobile Callback Formats After the hosted connection flow completes, MarketingBlocks redirects the user back to the **client mobile app callback URL**. Supported mobile callback formats include: #### Custom app URL scheme ``` clientapp://social/callback ``` #### Universal / app link ``` https://mobile.client.com/social/callback ``` *** ### Callback Response #### Single-channel platforms After successful connection, your application may receive: ``` https://client.example.com/callback?channel_id=254&platform=linkedin&status=success&connect_token=abc123 ``` #### Facebook multi-page flow Facebook may return multiple connected channels: ``` https://client.example.com/callback?channel_ids=45,46,47&platform=facebook&status=success&connect_token=abc123 ``` #### Mobile custom scheme callback example ``` clientapp://social/callback?channel_id=254&platform=instagram&status=success&connect_token=abc123 ``` #### Mobile universal link callback example ``` https://mobile.client.com/social/callback?channel_id=254&platform=instagram&status=success&connect_token=abc123 ``` *** ### Check Connection Status For mobile fallback and AI agent / CLI integrations, use the connection status endpoint. #### Endpoint **GET** `https://app.marketingblocks.ai/api/v1/social-sparks/connect-status?connect_token=` #### Example Request ```bash curl --location 'https://app.marketingblocks.ai/api/v1/social-sparks/connect-status?connect_token=abc123' \ --header 'Authorization: Bearer ' ``` #### Success Response ```json { "status": true, "expired": false, "connect_status": "success", "platform": "linkedin", "channel_id": 254, "channel_ids": null, "account_name": "Acme LinkedIn Page", "message": "Connection successful", "updated_at": "2026-05-15T10:02:00+00:00" } ``` #### Pending Response ```json { "status": true, "expired": false, "connect_status": "pending", "platform": null, "channel_id": null, "channel_ids": null, "account_name": null, "message": null, "updated_at": "2026-05-15T10:00:00+00:00" } ``` #### Failed Response ```json { "status": true, "expired": false, "connect_status": "failed", "platform": "linkedin", "channel_id": null, "channel_ids": null, "account_name": null, "message": "User denied permissions", "updated_at": "2026-05-15T10:02:00+00:00" } ``` #### Expired Response ```json { "status": false, "expired": true, "connect_status": "expired" } ``` *** ### Usage Notes * `connect_url` is temporary and should be used immediately. * `connect_token` is temporary and can be used to validate or poll connection status. * `expires_in` is currently `900` seconds. * Web clients can continue using the redirect flow exactly as before. * Mobile apps may use: * HTTPS callback URLs * universal links * app links * custom deep links * AI agents / CLI tools may omit `redirectUrl` and use polling instead. * Facebook may connect multiple pages and return `channel_ids`. * All OAuth and social platform handling is managed by MarketingBlocks. ### Supported Platforms The connection flow may support the following platforms depending on account availability and permissions: * Facebook * Instagram * Twitter / X * LinkedIn * YouTube * TikTok *** ### Possible Errors | HTTP Status | Description | | --------------------------- | ---------------------------------------------------------- | | `401 Unauthorized` | Missing or invalid bearer token. | | `422 Unprocessable Entity` | Missing required fields such as `userId` or `redirectUrl`. | | `404 Not Found` | Connection session expired when checking status. | | `500 Internal Server Error` | Unexpected server-side error occurred. | *** ### Example Error Response ```json { "status": false, "message": "The redirectUrl field is required." } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.marketingblocks.ai/agentic-ai-docs/api-reference/social-growth-engine/channels/connect-channel.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.