Listings APIListings API
登入

Social

透過 client.social 管理品牌、連結社群帳號，並在 Facebook、Instagram、X、LinkedIn 和 Pinterest 發布貼文或排程發布貼文。

所有 Social 方法都位於 client.social 下，分為 4 個命名空間，另有 1 個頂層呼叫：

命名空間管理項目
client.social.brands品牌：包含已連結帳號和貼文的容器
client.social.connections連結至品牌的 Social 帳號
client.social.posts個別貼文：草稿、排程、發布、取消、成效分析
client.social.bulk以非同步工作在單一請求中處理多篇貼文
client.social.limits()連線數量上限與目前用量

ID、平台與狀態

品牌、貼文和連線 ID 都是一般的 UUID 字串。與地點 ID 不同，這些 ID 一律不使用 Base64 編碼，SDK 也不會轉換它們。

平台使用大寫列舉值 FACEBOOK、INSTAGRAM、TWITTER（即 X）、LINKEDIN 和 PINTEREST。貼文狀態為 DRAFT、PENDING、SCHEDULED、PUBLISHED、FAILED、ARCHIVED 和 REJECTED；各管道的狀態為 SCHEDULED、SUCCESS、ERROR 和 ARCHIVED。

每次寫入都會傳回 success 旗標

Social 寫入操作會在 200 回應內以 success: false 回報驗證失敗，並在 error 中提供原因。SDK 會在發生傳輸錯誤或收到可辨識的錯誤酬載時引發例外，但您仍應養成自行檢查 success 的習慣：

Python
result = client.social.brands.create(profile_name="Jenny Home", timezone=tz)if not result.success:  raise RuntimeError(result.error.message)

發布以非同步方式執行

action="PUBLISH" 會接受貼文並傳回其 id。請輪詢 social.posts.retrieve() 並讀取 connectedChannels[]，以取得各管道的 status、liveLink 和 error；同一次呼叫中的貼文可能在某個平台發布成功，卻在另一個平台失敗。

social.brands.create

建立品牌。只有 profile_name 和 timezone 為必填。

Python
client.social.brands.create(    *,    profile_name: str,    timezone: dict,    business_intent: str | None = None,    categories: list[str] | None = None,    site_url: str | None = None,    logo: str | None = None,    country_iso: str | None = None,    bio: str | None = None,    brand_hashtags: list[str] | None = None,    competitor_hashtags: list[str] | None = None,    content_preferred_language: str | None = None,) -> APIObject
引數型別說明
profile_namestr品牌的顯示名稱。必填。
timezonedict{"label", "tzCode", "name", "utc"}。tzCode 是 IANA 時區，此品牌的每個 schedule_date／schedule_time 都會依此時區解讀。必填。
business_intentstr商家的業務內容，用於提供內容建議。預設為 general。
categorieslist[str]商家類別。預設為空清單。
site_urlstr品牌網站。設定後會將讀取該網站的工作加入佇列。
logostr品牌標誌的公開 https URL。
country_isostr2 個字母的 ISO 國家代碼。
biostr品牌簡介。
brand_hashtagslist[str]在貼文編輯器中提供的建議主題標籤。
competitor_hashtagslist[str]要追蹤的競爭對手主題標籤。
content_preferred_languagestr生成內容使用的語言，e.g。en。
Python
result = client.social.brands.create(  profile_name="Jenny Home",  timezone={      "label": "(GMT-05:00) Eastern Time",      "tzCode": "America/New_York",      "name": "Eastern Standard Time",      "utc": "-05:00",  },  business_intent="A family-run home furnishings store selling handmade furniture.",  categories=["Furniture Store"],  site_url="https://jennyhome.example",)brand_id = result.socialProfile.id  # a plain UUID string

API 方案不限制品牌數量，因此此操作不會因數量上限而失敗。用量計算的是連線數量，請在產生連線連結前檢查 social.limits()，而非在建立品牌前檢查。

social.brands.list

列出品牌，使用位移分頁。若您提供篩選條件，其中必須包含 statuses。

Python
client.social.brands.list(    *,    statuses: list[str] | None = None,    profile_name: str | None = None,    page: int | None = None,    size: int | None = None,) -> APIObject
Python
result = client.social.brands.list(page=1, size=25)for brand in result.profiles:  print(brand.id, brand.profileName, brand.connectedChannelCount)print(result.pageInfo.total, result.pageInfo.hasNextPage)

social.brands.retrieve

依 UUID 取得單一品牌。

Python
client.social.brands.retrieve(brand_id: str) -> APIObject
Python
brand = client.social.brands.retrieve("6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902")print(brand.profileName, brand.timezone.tzCode)

social.brands.update

更新品牌。只有 profile_id 為必填；只需傳送您要變更的欄位。

Python
client.social.brands.update(    profile_id: str,    *,    profile_name: str | None = None,    timezone: dict | None = None,    business_intent: str | None = None,    categories: list[str] | None = None,    site_url: str | None = None,    logo: str | None = None,    country_iso: str | None = None,    bio: str | None = None,    brand_hashtags: list[str] | None = None,    competitor_hashtags: list[str] | None = None,    content_preferred_language: str | None = None,) -> APIObject

傳送 categories、brand_hashtags 和 competitor_hashtags 時，會取代已儲存的清單；傳入 [] 則會清空清單。

Python
client.social.brands.update(  "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",  profile_name="Jenny Home & Co.",)

social.brands.archive

封存品牌及其連線。品牌必須已建立至少 90 天。

Python
client.social.brands.archive(social_profile_id: str) -> APIObject
Python
result = client.social.brands.archive("6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902")print(result.status)  # ARCHIVED or TENURE_NOT_MET

若品牌建立未滿 90 天，會傳回 success: False 和 status: "TENURE_NOT_MET"，且不會變更任何內容。達到建立天數要求後，封存會立即生效：品牌及其所有連線都會在同一次呼叫中封存，並立即停止發布，但這些連線仍會占用名額，直到計費週期結束，與手動中斷連線的行為完全相同。

產生短效的代管頁面 URL，引導終端使用者將一個平台連結至品牌。請將使用者重新導向至 url。

Python
client.social.connections.link(    brand_id: str,    *,    channel: str,    redirect_url: str,    error_url: str | None = None,    state: str | None = None,) -> APIObject
Python
link = client.social.connections.link(  "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",  channel="INSTAGRAM",  redirect_url="https://app.example.com/social/connected",  error_url="https://app.example.com/social/connect-failed",  state="sess_9f2c1e64",)print(link.url, link.expiresIn)

使用者會返回 redirect_url，其中會附加 status、brandId、platform、您提供的 state，成功時還會附加 connectedAccountId。連線會稍後才實際建立，因此請持續輪詢 social.connections.list() 數秒，不要將第一次讀取的空結果視為失敗。Instagram 必須使用已連結至 Facebook 粉絲專頁的商業帳號或創作者帳號。

social.connections.list

列出品牌所連結的社群帳號。

Python
client.social.connections.list(brand_id: str) -> APIObject
Python
result = client.social.connections.list("6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902")for channel in result.socialConnected:  print(channel.id, channel.platform, channel.displayName)print(result.channelCount)

channel.id 是其他所有呼叫所需的連線 UUID；referenceId 是平台本身的帳號識別碼，一律不接受作為輸入。

social.connections.disconnect

移除連線。此操作無法復原：若要恢復連線，必須重新執行 social.connections.link()。

Python
client.social.connections.disconnect(social_profile_connected_channel_id: str) -> APIObject
Python
client.social.connections.disconnect("b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7")

以該管道為目標的排程貼文不會取消；它們會在發布時失敗，並傳回 SY95045。請先使用 social.posts.cancel() 取消這些貼文。

social.posts.create

為單一品牌建立一篇貼文，發布至其已連結的管道。

Python
client.social.posts.create(    *,    social_profile_id: str,    name: str,    platforms: list[str],    content: str,    action: str,    media_urls: list[str] | None = None,    video_urls: list[str] | None = None,    link: str | None = None,    scheduled_at: str | None = None,    schedule_date: str | None = None,    schedule_time: str | None = None,    connected_channel_ids: list[str] | None = None,    client_reference: str | None = None,) -> APIObject
引數型別說明
social_profile_idstr品牌 UUID。必填。
namestr內部名稱，不會向受眾顯示。必填。
platformslist[str]FACEBOOK、INSTAGRAM、TWITTER、LINKEDIN、PINTEREST。每個平台都必須已在該品牌下建立連線。必填。
contentstr貼文本文。必填。
actionstrDRAFT、SCHEDULE 或 PUBLISH。必填。
media_urlslist[str]公開的 https 圖片 URL。Instagram 和 Pinterest 必填。
video_urlslist[str]公開的 https 影片 URL。
linkstr要附加的連結，僅適用於支援連結的平台。
scheduled_atstr含時區偏移量的 ISO-8601 格式。可用來替代日期與時間欄位組合。
schedule_datestrYYYY-MM-DD，依品牌的時區解讀。請與 schedule_time 一併傳送。
schedule_timestrHH:MM，依品牌的時區解讀。請與 schedule_date 一併傳送。
connected_channel_idslist[str]限制為特定連線。
client_referencestr您自訂的識別碼，會在批次工作結果中原樣傳回。

action="SCHEDULE" 必須且只能使用一種排程形式：scheduled_at，或 schedule_date + schedule_time。同時傳送兩種形式會遭到拒絕，並傳回 SY95046。

Python
result = client.social.posts.create(  social_profile_id="6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",  name="Autumn collection launch",  platforms=["INSTAGRAM", "FACEBOOK"],  content="Our autumn collection lands today. Solid oak, hand-finished.",  media_urls=["https://cdn.example.com/social/autumn.jpg"],  action="SCHEDULE",  schedule_date="2026-10-02",  schedule_time="09:30",)print(result.success, result.socialPostId)

social.posts.retrieve

取得單一貼文及其各管道的發布狀態。建立貼文後，請輪詢此呼叫。

Python
client.social.posts.retrieve(post_id: str) -> APIObject
Python
post = client.social.posts.retrieve("c47a1e58-2b93-4f10-a6d7-58e0c9b12345")print(post.status)for channel in post.connectedChannels:  print(channel.platform, channel.status, channel.liveLink, channel.error)

social.posts.list

列出品牌的貼文，使用位移分頁，並支援篩選條件。

Python
client.social.posts.list(    brand_id: str,    *,    filters: dict | None = None,    page: int | None = None,    size: int | None = None,    fetch_post_content: bool | None = None,) -> APIObject

filters 接受 name、platforms、status、start_date、end_date、social_connected_channel_id、approval_state、view_mode 和 filter_by_user。

Python
result = client.social.posts.list(  "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",  filters={"status": ["SCHEDULED"], "startDate": "2026-10-01", "endDate": "2026-10-31"},  page=1,  size=50,)for post in result.socialPosts:  print(post.socialPostId, post.name, post.status)print(result.pageInfo.total)

social.posts.cancel

取消排程貼文或草稿貼文，使其不再發布。

Python
client.social.posts.cancel(social_post_id: str) -> APIObject
Python
client.social.posts.cancel("c47a1e58-2b93-4f10-a6d7-58e0c9b12345")

已發布的貼文無法取消，也不會從任何平台移除；對於這類貼文，此呼叫會傳回 success: False。

social.posts.insights

單一已發布貼文在單一管道上的互動資料與留言。兩個欄位都會以 JSON 字串傳回，內含平台本身的酬載。

Python
client.social.posts.insights(    post_id: str,    *,    social_connected_channel_id: str,) -> APIObject
Python
import json result = client.social.posts.insights(  "c47a1e58-2b93-4f10-a6d7-58e0c9b12345",  social_connected_channel_id="b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7",)insights = json.loads(result.insights)comments = json.loads(result.comments)print(insights.get("impressions"), len(comments))

其中的鍵由平台定義，且因平台而異；讀取時請檢查並處理非預期情況。

social.bulk.create

在單一請求中驗證最多 500 篇貼文，並將其加入佇列。各列可指定不同品牌。

Python
client.social.bulk.create(    posts: list[dict],    *,    name: str | None = None,) -> APIObject

每列都在 camelCase 中使用與 social.posts.create 相同的欄位。若任何一列無效，就不會建立任何內容：success 為 False，SY95050 會在 error 中傳回，而 job.results[] 會以每個無效列從 0 起算的 index 及其 clientReference 識別該列。

Python
result = client.social.bulk.create([  {      "socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",      "name": "Autumn week 1",      "platforms": ["INSTAGRAM", "FACEBOOK"],      "content": "Week one of the autumn collection.",      "mediaUrls": ["https://cdn.example.com/social/autumn-w1.jpg"],      "action": "SCHEDULE",      "scheduleDate": "2026-10-02",      "scheduleTime": "09:30",      "clientReference": "campaign-4471-slot-01",  },])if not result.success:  for row in result.job.results:      print(row.index, row.clientReference, row.errors)else:  job_id = result.job.id

social.bulk.retrieve

輪詢批次工作，直到其狀態進入終止狀態。

Python
client.social.bulk.retrieve(bulk_job_id: str) -> APIObject
Python
job = client.social.bulk.retrieve("9b3f18d0-7a26-4c51-8e94-1f0d5c6b7a82")print(job.status, job.processedCount, "/", job.totalCount)for row in job.results:  print(row.clientReference, row.status, row.socialPostId)

status 為 QUEUED、PROCESSING、COMPLETED、COMPLETED_WITH_ERRORS 或 FAILED。某列達到 CREATED 表示貼文已存在，不代表已發布：請將 socialPostId 傳入 social.posts.retrieve()，以取得各管道的結果。

social.limits

以單次呼叫取得連線數量上限與目前用量。

Python
client.social.limits() -> APIObject
Python
limits = client.social.limits()print(limits.maxConnections, limits.usage.connections)     # pool vs usedprint(limits.brands)                                       # None — brands are unlimitedprint(limits.usage.brands)                                 # brands that exist, uncapped

連線名額由整個帳號共用，並非各品牌分別享有：Social Launch 提供 20 個，Social Growth 提供 125 個，每加購 1 個每月 $25 的連線套件則增加 5 個。請在產生連線連結前檢查用量，以便向使用者顯示升級選項，而非 SY95042。所有 API 方案的 limits.brands 都是 None。

另請參閱