Listings APIListings API
Masuk

Social

Kelola merek, hubungkan akun sosial, dan terbitkan atau jadwalkan postingan ke Facebook, Instagram, X, LinkedIn dan Pinterest melalui client.social.

Semua metode Social berada di client.social, dikelompokkan ke dalam empat namespace ditambah satu pemanggilan tingkat atas:

NamespaceMengelola
client.social.brandsMerek: wadah yang menaungi akun terhubung dan postingan
client.social.connectionsAkun Social yang ditautkan ke merek
client.social.postsPostingan individual: draf, penjadwalan, publikasi, pembatalan, analitik
client.social.bulkBanyak postingan dalam satu permintaan, sebagai tugas asinkron
client.social.limits()Batas koneksi dan penggunaan saat ini

ID, platform, dan status

ID merek, postingan, dan koneksi berupa string UUID biasa. Berbeda dari ID lokasi, ID tersebut tidak pernah dienkode dengan Base64, dan SDK tidak mengubahnya.

Platform menggunakan nilai enum berhuruf kapital FACEBOOK, INSTAGRAM, TWITTER (yaitu X), LINKEDIN, dan PINTEREST. Status postingan adalah DRAFT, PENDING, SCHEDULED, PUBLISHED, FAILED, ARCHIVED, dan REJECTED; status per kanal adalah SCHEDULED, SUCCESS, ERROR, dan ARCHIVED.

Setiap operasi tulis mengembalikan flag success

Operasi tulis Social melaporkan kegagalan validasi di dalam respons 200, sebagai success: false dengan alasannya di error. SDK memunculkan exception saat terjadi kesalahan transport dan saat menerima payload kesalahan yang dikenali, tetapi sebaiknya Anda tetap memeriksa success sendiri:

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

Publikasi berlangsung secara asinkron

action="PUBLISH" menerima postingan dan mengembalikan ID-nya. Lakukan polling pada social.posts.retrieve() dan baca connectedChannels[] untuk mendapatkan status, liveLink, dan error per kanal; suatu postingan dapat berhasil di satu platform dan gagal di platform lain dalam pemanggilan yang sama.

social.brands.create

Buat merek. Hanya profile_name dan timezone yang wajib diisi.

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
ArgumenTipeDeskripsi
profile_namestrNama tampilan merek. Wajib diisi.
timezonedict{"label", "tzCode", "name", "utc"}. tzCode adalah zona waktu IANA yang digunakan untuk menafsirkan setiap schedule_date / schedule_time pada merek ini. Wajib diisi.
business_intentstrKegiatan bisnis, digunakan untuk saran konten. Nilai default adalah general.
categorieslist[str]Kategori bisnis. Nilai default adalah daftar kosong.
site_urlstrSitus web merek. Mengisinya akan memasukkan pembacaan situs ke antrean.
logostrURL https publik untuk logo merek.
country_isostrKode negara ISO dua huruf.
biostrProfil singkat merek.
brand_hashtagslist[str]Tagar yang ditawarkan sebagai saran di editor postingan.
competitor_hashtagslist[str]Tagar pesaing yang akan dipantau.
content_preferred_languagestrBahasa untuk konten yang dihasilkan, 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

Jumlah merek tidak dibatasi pada paket API, sehingga operasi ini tidak pernah gagal karena batas jumlah merek. Yang dihitung adalah koneksi — periksa social.limits() sebelum membuat tautan koneksi, bukan sebelum membuat merek.

social.brands.list

Tampilkan daftar merek dengan paginasi berbasis offset. statuses wajib disertakan di dalam filter jika Anda mengirimkan filter.

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

Ambil satu merek berdasarkan UUID-nya.

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

Perbarui merek. Hanya profile_id yang wajib diisi; kirim hanya field yang Anda ubah.

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, dan competitor_hashtags menggantikan daftar yang tersimpan saat dikirim; mengirimkan [] akan mengosongkannya.

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

social.brands.archive

Arsipkan merek beserta koneksinya. Merek harus sudah berusia minimal 90 hari.

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

Untuk merek yang berusia kurang dari 90 hari, respons mengembalikan success: False dan status: "TENURE_NOT_MET", dan tidak ada yang berubah. Setelah persyaratan usia terpenuhi, pengarsipan berlangsung seketika: merek dan setiap koneksi yang ditautkan ke merek tersebut diarsipkan dalam pemanggilan yang sama dan langsung berhenti menerbitkan postingan, tetapi slot koneksinya tetap terpakai hingga akhir siklus penagihan, sama seperti saat koneksi diputus secara manual.

Buat URL yang dihosting dan berlaku singkat untuk memandu pengguna akhir menghubungkan satu platform ke merek. Alihkan pengguna ke 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)

Pengguna kembali ke redirect_url dengan tambahan status, brandId, platform, state Anda, dan, jika berhasil, connectedAccountId. Koneksi baru terbentuk beberapa saat kemudian, jadi lakukan polling pada social.connections.list() selama beberapa detik alih-alih menganggap hasil pembacaan pertama yang kosong sebagai kegagalan. Instagram memerlukan akun Business atau Creator yang ditautkan ke Halaman Facebook.

social.connections.list

Tampilkan daftar akun media sosial yang terhubung ke merek.

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 adalah UUID koneksi yang diperlukan oleh setiap pemanggilan lainnya; referenceId adalah pengenal akun milik platform dan tidak pernah diterima sebagai input.

social.connections.disconnect

Hapus koneksi. Tindakan ini tidak dapat dibatalkan: untuk memulihkannya, diperlukan social.connections.link() baru.

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

Postingan terjadwal yang menargetkan kanal tersebut tidak dibatalkan; postingan tersebut akan gagal pada waktu publikasi dengan SY95045. Batalkan terlebih dahulu dengan social.posts.cancel().

social.posts.create

Buat satu postingan untuk satu merek di seluruh kanal yang terhubung dengannya.

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
ArgumenTipeDeskripsi
social_profile_idstrUUID merek. Wajib diisi.
namestrNama internal, tidak ditampilkan kepada audiens. Wajib diisi.
platformslist[str]FACEBOOK, INSTAGRAM, TWITTER, LINKEDIN, PINTEREST. Masing-masing harus sudah memiliki koneksi pada merek tersebut. Wajib diisi.
contentstrIsi postingan. Wajib diisi.
actionstrDRAFT, SCHEDULE, atau PUBLISH. Wajib diisi.
media_urlslist[str]URL https publik untuk gambar. Wajib diisi untuk Instagram dan Pinterest.
video_urlslist[str]URL https publik untuk video.
linkstrTautan untuk dilampirkan jika platform mendukungnya.
scheduled_atstrISO-8601 dengan offset. Alternatif untuk pasangan tanggal/waktu.
schedule_datestrYYYY-MM-DD, ditafsirkan dalam zona waktu merek. Kirim bersama schedule_time.
schedule_timestrHH:MM, ditafsirkan dalam zona waktu merek. Kirim bersama schedule_date.
connected_channel_idslist[str]Batasi ke koneksi tertentu.
client_referencestrPengenal Anda sendiri, dikembalikan dalam hasil tugas massal.

action="SCHEDULE" memerlukan tepat satu bentuk jadwal: scheduled_at, atau schedule_date + schedule_time. Pengiriman keduanya ditolak dengan 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

Ambil satu postingan beserta status publikasinya per kanal. Lakukan polling pada metode ini setelah membuat postingan.

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

Tampilkan daftar postingan merek dengan paginasi berbasis offset dan filter.

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 menerima name, platforms, status, start_date, end_date, social_connected_channel_id, approval_state, view_mode, dan 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

Batalkan postingan terjadwal atau draf agar tidak pernah diterbitkan.

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

Postingan yang sudah diterbitkan tidak dapat dibatalkan dan tidak dihapus dari platform mana pun; pemanggilan ini mengembalikan success: False untuk postingan tersebut.

social.posts.insights

Interaksi dan komentar untuk satu postingan yang telah diterbitkan di satu kanal. Kedua field dikembalikan sebagai string JSON yang memuat payload milik platform.

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))

Key di dalamnya ditentukan oleh platform dan berbeda untuk setiap platform; tangani kemungkinan perbedaan saat membacanya.

social.bulk.create

Validasi dan masukkan hingga 500 postingan ke antrean dalam satu permintaan. Setiap baris dapat menargetkan merek yang berbeda.

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

Setiap baris menerima field yang sama dengan social.posts.create, di dalam camelCase. Jika ada satu saja baris yang tidak valid, tidak ada yang dibuat: success bernilai False, SY95050 dikembalikan di error, dan job.results[] mengidentifikasi setiap baris yang tidak valid berdasarkan index yang dimulai dari 0 dan clientReference-nya.

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

Lakukan polling pada tugas massal hingga mencapai status akhir.

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 bernilai QUEUED, PROCESSING, COMPLETED, COMPLETED_WITH_ERRORS, atau FAILED. Baris yang mencapai CREATED berarti postingan sudah ada, bukan sudah diterbitkan: gunakan socialPostId pada social.posts.retrieve() untuk mendapatkan hasil per kanal.

social.limits

Batas koneksi dan penggunaan saat ini, dalam satu pemanggilan.

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

Koneksi menggunakan kuota bersama untuk seluruh akun — 20 pada Social Launch, 125 pada Social Growth, ditambah 5 untuk setiap paket koneksi seharga $25/bulan — bukan kuota per merek. Periksa kuota tersebut sebelum membuat tautan koneksi agar Anda dapat menampilkan opsi peningkatan paket alih-alih SY95042. limits.brands bernilai None pada setiap paket API.

Lihat juga