Listings APIListings API
登入
POST/api/v4/posts

建立公告貼文

建立 ANNOUNCEMENT 社群貼文，並將其發布至一個或多個地點的指定網站。

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

參數

請求主體

名稱類型必填說明
inputobject必填Wrapper object. Every field below is a property of `input`, the entire body must be nested under it.
input.postNamestring必填Internal name for the campaign (not shown to customers).
input.locationIdsarray of strings必填Base64-encoded location IDs to publish to (e.g. `TG9jYXRpb246MTgwMDI4OQ==`).
input.postTypestring必填Must be `ANNOUNCEMENT`. One of EVENT, OFFER, ANNOUNCEMENT, COVID19, PRODUCT.
input.postSitesarray of strings必填Sites to publish to: `GOOGLE`, `FACEBOOK`.
input.postMessagearray of objects選填Per-site body text: `{ site, message }`. Provide one entry per site in `postSites`.
input.postCtaarray of objects選填Optional call-to-action button per site: `{ site, type, url }`. `type` is one of BOOK, ORDER, SHOP, LEARN_MORE, SIGN_UP, GET_OFFER.
input.postMediaUrlarray of objects選填Optional media per site: `{ site, url, type }` where `type` is IMAGE or VIDEO.
input.clientMutationIdstring選填Optional client token returned unchanged in the response for correlation.

請求範例

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

Request body
{  "input": {    "postName": "Grand Opening Announcement",    "locationIds": ["TG9jYXRpb246MTgwMDI4OQ=="],    "postType": "ANNOUNCEMENT",    "postSites": ["GOOGLE"],    "postMessage": [      { "site": "GOOGLE", "message": "We are now open! Visit Jenny Home this week for our grand opening." }    ],    "postCta": [      { "site": "GOOGLE", "type": "LEARN_MORE", "url": "https://jennyhome.example/opening" }    ],    "postMediaUrl": [      { "site": "GOOGLE", "url": "https://cdn.example.com/opening.jpg", "type": "IMAGE" }    ]  }}

回應

200Post accepted. Publishing runs asynchronously, the returned post starts as INPROGRESS.
Response
{  "data": {    "createSocialPost": {      "clientMutationId": null,      "success": true,      "errors": [],      "socialPost": {        "id": "U29jaWFsUG9zdDo0NDEyMg==",        "name": "Grand Opening Announcement",        "status": "INPROGRESS",        "type": "ANNOUNCEMENT",        "createdAt": "2026-06-28",        "sites": ["GOOGLE"],        "message": [          { "site": "GOOGLE", "message": "We are now open! Visit Jenny Home this week for our grand opening." }        ],        "cta": [          { "type": { "value": "LEARN_MORE", "label": "Learn more" }, "url": "https://jennyhome.example/opening", "site": "GOOGLE", "tinyUrl": null }        ],        "contextInfo": null,        "mediaUrl": [          { "url": "https://cdn.example.com/opening.jpg", "site": "GOOGLE", "type": "IMAGE" }        ],        "publishDetails": [          { "site": "GOOGLE", "status": "PUBLISHING", "createdDate": "2026-06-28", "submissionError": null }        ],        "postLinks": [],        "locationIds": [1800289]      }    }  }}
400Bad request, the body was not wrapped in `input` (error message: `Variable "$input" of required type "CreateSocialPostMutationInput!" was not provided`).
401Unauthenticated, missing or invalid API key.

建立公告：最簡單的貼文類型。公告包含純文字訊息（以及選填的 CTA 和圖片），不含活動日期或優惠詳情。傳入 postType: "ANNOUNCEMENT"，並在 postSites 中為每個網站提供一筆 postMessage 項目。

使用案例：向您各門市的顧客宣告「我們開幕了」。 透過一次呼叫，為一組地點在 Google（及 Facebook）上發布盛大開幕或新營業時間的公告。提供連結至您網站的 LEARN_MORE CTA 和圖片，讓卡片內容更豐富。此呼叫會立即傳回 status: INPROGRESS；使用傳回的 socialPost.id 輪詢 GET /posts/{postId}，直到其值為 SUCCESS，若有任何網站發布失敗，請讀取 publishDetails[].submissionError。

注意事項。

  • 請求主體必須包在 input 物件中：每個欄位（postName、locationIds、postType、postSites、……）都是 input 的屬性。未包裝的扁平主體會遭到拒絕，並傳回 HTTP 400（Variable "$input" of required type "CreateSocialPostMutationInput!" was not provided）。
  • postSites 和每個 postMessage.site 都使用網站列舉值（GOOGLE、FACEBOOK）；請為每個目標網站提供一筆訊息項目。
  • 若要將相同公告發布至多個地點，您可以在此處的 locationIds 中傳入所有 ID，或使用 POST /bulk-posts 進行大規模的多地點發布。
  • 含有日期的貼文請使用 活動；優惠券／折扣請使用 優惠。

寫入操作：未在正式帳戶上執行。此處顯示的請求和回應是根據 API 結構描述建構的；執行時，此操作會發布至真實的 Google／Facebook 商家檔案。

Request
curl -X POST 'https://listingsapi.com/api/v4/posts' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "postName": "Grand Opening Announcement",      "locationIds": [        "TG9jYXRpb246MTgwMDI4OQ=="      ],      "postType": "ANNOUNCEMENT",      "postSites": [        "GOOGLE"      ],      "postMessage": [        {          "site": "GOOGLE",          "message": "We are now open! Visit Jenny Home this week for our grand opening."        }      ],      "postCta": [        {          "site": "GOOGLE",          "type": "LEARN_MORE",          "url": "https://jennyhome.example/opening"        }      ],      "postMediaUrl": [        {          "site": "GOOGLE",          "url": "https://cdn.example.com/opening.jpg",          "type": "IMAGE"        }      ]    }  }'
Run in playground