Listings APIListings API
登入
POST/api/v4/social/brands/{brandId}/connections/link

取得連線連結

傳回有效時間短暫的託管網址，引導終端使用者將一個社群平台連線至品牌。

需要 API 金鑰。標頭格式與金鑰輪替請參閱驗證。

參數

路徑

名稱類型必填說明
brandIdstring必填Brand UUID the connection will be attached to.

請求主體

名稱類型必填說明
channelstring必填Platform to connect: `FACEBOOK`, `INSTAGRAM`, `TWITTER` (X), `LINKEDIN` or `PINTEREST`.
redirectUrlstring必填Absolute https URL in your application the user is returned to when the flow finishes. Must be a URL you control.
errorUrlstring選填Absolute https URL the user is returned to if they cancel or the platform rejects the authorization. Defaults to `redirectUrl` when omitted.
statestring選填Opaque string echoed back on the return URL unchanged. Use it to correlate the return with the session that started the flow; it is not validated or interpreted.

請求範例

可直接貼上的請求主體。請將預留位置 ID 與值換成您自己的。

Request body
{  "channel": "INSTAGRAM",  "redirectUrl": "https://app.example.com/social/connected",  "errorUrl": "https://app.example.com/social/connect-failed",  "state": "sess_9f2c1e64"}

回應

200Link generated. Redirect the end user to `url`; `expiresIn` is how many seconds it stays valid.
Response
{  "data": {    "connectSocialAccount": {      "status": "success",      "url": "https://social.listingsapi.com/connect/start?token=bfac8e06-8d72-4810-9c50-ae7ee12a7b52",      "title": null,      "token": null,      "expiresIn": 900    }  }}
200The link could not be issued. `status` is `failed` and `title` carries the reason: most often the account is at its connection cap (`SY95042`, counted on billable connections, so recent disconnects have not freed room) or the platform is not enabled for the account (`SY95044`).
Response
{  "data": {    "connectSocialAccount": {      "status": "failed",      "url": null,      "title": "SY95042: Connection limit reached for this account",      "token": null,      "expiresIn": null    }  }}
401Unauthenticated, missing or invalid API key.
404No brand with that ID on this account (`SY95043`).

核發有效時間短暫的網址，用於將一個社群平台連線至一個品牌。您完全不需處理平台的 OAuth 憑證：將終端使用者重新導向至傳回的 url，使用者完成平台的授權同意畫面並選擇要發布內容的粉絲專頁、看板或組織後，就會返回您的 redirectUrl。

這是 Social 唯一使用扁平結構主體的寫入操作。Social API 的其他所有寫入操作都包裝在 input 物件中；只有這個操作例外。在最上層傳送 channel、redirectUrl，以及選用的 errorUrl 和 state。

使用案例：在您的產品內自助連線至管道。向使用者顯示 5 個平台，當他們選擇其中一個時，使用該 channel 和可識別其工作階段的 state 呼叫此端點。將使用者重新導向至 url。當他們返回您的 redirectUrl 並帶有 status=success 時，輪詢 GET /social/brands/{brandId}/connections，直到新管道出現，再讓他們使用 POST /social/posts 撰寫第一篇貼文。

使用者返回的目的地

流程結束時，使用者會被導向您的 redirectUrl（或 errorUrl），並附加以下查詢參數：

參數是否一律提供說明
status是success 或 error。
brandId是此連線所屬的品牌。與您呼叫時使用的路徑參數相符。
platform是已連線的平台，例如 INSTAGRAM。
state僅在您有傳送時提供您提供的不透明值，會原封不動地傳回。
connectedAccountId僅在 status=success 時提供新連線的 UUID，與連線清單中顯示的 id 相同。
Code
https://app.example.com/social/connected  ?status=success  &brandId=6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902  &platform=INSTAGRAM  &state=sess_9f2c1e64  &connectedAccountId=b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7

注意事項。

  • 連結會到期。expiresIn 包含以秒為單位的有效時間。此連結只能使用一次：請在使用者點擊「連線」時才核發，不要提前核發，也絕不可儲存。如果使用者放棄流程，請再次呼叫此端點以取得新的網址。
  • 連線記錄會以非同步方式建立。使用者返回您的 redirectUrl 時，連線記錄還需要片刻才會建立，因此在使用者返回後立即讀取連線清單，結果中沒有該連線屬於正常情況。請持續輪詢連線清單幾秒鐘，不要將第一次讀取的空結果視為失敗。
  • Instagram 需要已連結至 Facebook 粉絲專頁的商業帳號或創作者帳號。個人 Instagram 帳號無法連線，平台的授權同意畫面也不會提供這類帳號供選擇。如果您的使用者遇到此情況，請讓他們在 Instagram 應用程式中轉換帳號類型，並將帳號連結至他們管理的粉絲專頁，然後重新核發連結。
  • TWITTER 就是 X。為了維持回溯相容性，列舉值仍保留為 TWITTER；產品名稱則是 X。平台值是大寫的列舉名稱，傳送 "instagram" 會遭到拒絕。
  • redirectUrl 和 errorUrl 必須是絕對 https 網址。相對網址或 http 網址會遭到拒絕，並傳回 SY95049。
  • 連線是計量資源。每次連結都會使用整個帳戶共用的連線額度：Social Launch 提供 20 個連線，Social Growth 提供 125 個連線，每個每月 $25 的連線套組可再增加 5 個，自助加購上限為 250 個。品牌本身的數量不限，因此用盡額度的一律是此呼叫，絕不會是建立品牌。當額度用盡時，連結請求會傳回 status: "failed"，並附帶 SY95042。請參閱方案與加購項目，並從 GET /social/limits 讀取您的剩餘額度。
  • 這是地點層級的 Facebook 連線連結在 Social 中對應的功能，但兩者是獨立產品，在其中一個產品建立的連線不會顯示於另一個產品。

寫入操作：未對正式帳戶執行。此處顯示的請求與回應是根據 API 結構描述建構的。

Request
curl -X POST 'https://listingsapi.com/api/v4/social/brands/<brandId>/connections/link' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "channel": "INSTAGRAM",    "redirectUrl": "https://app.example.com/social/connected",    "errorUrl": "https://app.example.com/social/connect-failed",    "state": "sess_9f2c1e64"  }'
Run in playground