게시물

client.posts를 통해 Google과 Facebook에 공지, 이벤트, 혜택을 게시합니다.

모든 게시물 메서드는 client.posts 아래에 있습니다. location_id을 받는 메서드는 숫자 ID 또는 base64로 인코딩된 ID를 허용합니다. 사업장 ID를 참고하세요.

게시물은 GOOGLE과 FACEBOOK의 2개 사이트에 게시됩니다. 게시물 유형은 ANNOUNCEMENT, EVENT, OFFER, COVID19, PRODUCT입니다. 클릭 유도 유형은 BOOK, ORDER, SHOP, LEARN_MORE, SIGN_UP, GET_OFFER이며, cta_type과 cta_url는 항상 함께 제공해야 합니다.

비동기 게시

게시는 비동기로 처리됩니다. 생성 호출은 status: INPROGRESS을 반환합니다. 상태가 SUCCESS이 될 때까지 posts.retrieve()(일괄 캠페인의 경우 posts.bulk_retrieve())을 폴링하고, publishDetails[].submissionError에서 사이트별 실패 여부를 확인합니다.

사이트별 메시지

모든 생성 메서드는 message에 일반 문자열 또는 사이트를 텍스트에 매핑하는 dict를 허용하며, 일반 문자열을 지정하면 모든 사이트에 동일한 텍스트를 게시합니다.

Python

message = {  "GOOGLE": "Book your summer checkup today!",  "FACEBOOK": "Summer checkups are here. Tag a friend who needs one!",}

message이 dict인 경우 sites의 모든 사이트에 대한 항목을 포함해야 하며, 하나라도 누락되면 SDK는 네트워크 호출을 수행하기 전에 ValidationError를 발생시킵니다.

`posts.bulk_publish`

한 번의 호출로 여러 사업장의 Google과 Facebook에 하나의 게시물을 게시합니다. 이 게시 방식을 권장합니다. sites은 기본적으로 두 사이트를 모두 포함하고, 단일 메시지(또는 사이트별 dict)는 사이트별 항목으로 확장되며, 사업장 ID는 자동으로 인코딩되고, 네트워크 호출 전에 클라이언트 측에서 페이로드를 검증합니다.

Python

client.posts.bulk_publish(    *,    name: str,    location_ids: list[str | int],    message: str | dict[str, str],    sites: list[str] | None = None,    post_type: str = "ANNOUNCEMENT",    cta_type: str | None = None,    cta_url: str | None = None,    media_url: str | None = None,    scheduled_dates: dict | None = None,    context_info: dict | None = None,    additional_fields: dict | None = None,) -> APIObject

인수	유형	설명
`name`	`str`	내부 캠페인 이름입니다(고객에게 표시되지 않습니다). 필수입니다.
`location_ids`	`list[str \| int]`	게시할 모든 사업장입니다(숫자 ID 또는 base64 ID). 필수입니다.
`message`	`str \| dict`	모든 사이트에 사용할 게시물 본문 또는 사이트별 dict입니다. 필수입니다.
`sites`	`list[str]`	대상 사이트입니다. 기본값은 `["GOOGLE", "FACEBOOK"]`입니다.
`post_type`	`str`	`ANNOUNCEMENT`(기본값), `EVENT`, `OFFER`, `COVID19` 또는 `PRODUCT`입니다.
`cta_type`	`str`	선택 사항인 클릭 유도 버튼이며, `cta_url`이 필요합니다.
`cta_url`	`str`	CTA 버튼의 연결 대상입니다.
`media_url`	`str`	모든 사이트에 첨부할 공개 이미지 URL이며, 선택 사항입니다.
`scheduled_dates`	`dict`	선택 사항인 `{"startDatetime", "endDatetime"}` 기간입니다.
`context_info`	`dict`	`post_type`에 필요한 경우 제공하는 이벤트 또는 혜택의 세부 정보입니다.
`additional_fields`	`dict`	중첩 없이 전달되어 그대로 병합되는 추가 camelCase 필드입니다.

Python

result = client.posts.bulk_publish(  name="Holiday hours",  location_ids=[16808, 16809, 16810],  message="Open until 10pm through the holidays!",  media_url="https://cdn.example.com/holiday.jpg",  cta_type="LEARN_MORE",  cta_url="https://example.com/holiday-hours",)print(result.socialPost.id, result.socialPost.status)  # INPROGRESS, publishes async

`posts.create_announcement`

일반 메시지에 CTA와 미디어를 선택적으로 포함하는 ANNOUNCEMENT 게시물을 생성합니다. sites의 기본값은 ["GOOGLE"]입니다.

Python

client.posts.create_announcement(    *,    name: str,    location_ids: list[str | int],    message: str | dict[str, str],    sites: list[str] | None = None,    cta_type: str | None = None,    cta_url: str | None = None,    media_url: str | None = None,    scheduled_dates: dict | None = None,    additional_fields: dict | None = None,) -> APIObject

Python

result = client.posts.create_announcement(  name="Grand Opening",  location_ids=[16808],  message="Acme Dental is now open!",  sites=["GOOGLE"],  cta_type="LEARN_MORE",  cta_url="https://acmedental.example.com/opening",)print(result.socialPost.id)

`posts.create_event`

제목과 시작 및 종료 기간이 있는 EVENT 게시물을 생성합니다. Google은 이벤트 제목을 필수로 요구하며, 누락되면 SDK는 ValidationError을 발생시킵니다. start_day와 end_day은 날짜(YYYY-MM-DD)이며, start_time와 end_time은 "10:00am"과 같은 표시용 문자열입니다.

Python

client.posts.create_event(    *,    name: str,    location_ids: list[str | int],    message: str | dict[str, str],    title: str,    start_day: str,    end_day: str,    start_time: str | None = None,    end_time: str | None = None,    sites: list[str] | None = None,    cta_type: str | None = None,    cta_url: str | None = None,    media_url: str | None = None,    scheduled_dates: dict | None = None,    additional_fields: dict | None = None,) -> APIObject

Python

result = client.posts.create_event(  name="Free checkup day",  location_ids=[16808],  message="Join us for free dental checkups!",  title="Free Checkup Day",  start_day="2026-08-01",  end_day="2026-08-01",  start_time="10:00am",  end_time="4:00pm",  cta_type="BOOK",  cta_url="https://acmedental.example.com/book",)print(result.socialPost.id)

`posts.create_offer`

쿠폰, 할인, 약관이 포함된 OFFER 게시물을 생성합니다. title은 혜택의 이름을 지정하며 필수이고, start_day와 end_day(YYYY-MM-DD)은 유효 기간의 시작과 끝을 지정합니다.

Python

client.posts.create_offer(    *,    name: str,    location_ids: list[str | int],    message: str | dict[str, str],    title: str,    coupon_code: str | None = None,    discount: str | None = None,    redeem_url: str | None = None,    terms_conditions: str | None = None,    start_day: str | None = None,    end_day: str | None = None,    sites: list[str] | None = None,    cta_type: str | None = None,    cta_url: str | None = None,    media_url: str | None = None,    scheduled_dates: dict | None = None,    additional_fields: dict | None = None,) -> APIObject

Python

result = client.posts.create_offer(  name="Summer whitening sale",  location_ids=[16808],  message="20% off teeth whitening all week!",  title="Summer Whitening Sale",  coupon_code="SUMMER20",  discount="20%",  redeem_url="https://acmedental.example.com/sale",  terms_conditions="One per patient. Not valid with other offers.",  start_day="2026-08-01",  end_day="2026-08-07",)print(result.socialPost.id)

`posts.create`

원시 본문 dict로 게시물을 생성합니다. camelCase에 필드를 중첩 없이 전달하면 헬퍼가 전송 전에 API에서 요구하는 input 객체로 감싸므로, 실제 전송 본문은 {"input": {...}}이며 절대로 중첩 없는 본문이 아닙니다. locationIds은 이미 base64로 인코딩되어 있어야 합니다. 키워드 인수, 자동 ID 인코딩, 클라이언트 측 검증을 사용하려면 위의 타입이 지정된 생성 메서드를 우선 사용합니다.

Python

client.posts.create(body: dict) -> APIObject

필수 항목: postName, locationIds(base64), postType, postSites.

Python

result = client.posts.create({  "postName": "Grand Opening",  "locationIds": ["TG9jYXRpb246MTY4MDg="],  "postType": "ANNOUNCEMENT",  "postSites": ["GOOGLE"],  "postMessage": [{"site": "GOOGLE", "message": "We are now open!"}],})print(result.socialPost.id)

`posts.retrieve`

게시물의 콘텐츠, 사이트별 게시 상태, 분석 데이터를 조회합니다. 생성 후 status이 SUCCESS이 될 때까지 이 메서드를 폴링합니다.

Python

client.posts.retrieve(post_id: str) -> APIObject

Python

post = client.posts.retrieve("U29jaWFsUG9zdDo0NDEyMg==")print(post.status)for detail in post.publishDetails:  print(detail.site, detail.submissionError)

`posts.delete`

게시물을 삭제하고 게시된 모든 사이트에서도 제거합니다.

Python

client.posts.delete(post_id: str) -> APIObject

Python

client.posts.delete("U29jaWFsUG9zdDo0NDEyMg==")

`posts.list_for_location`

특정 사업장을 대상으로 하는 게시물 캠페인 목록을 조회합니다. 오프셋 기반 페이지 매김을 사용하며, 결과에는 .records과 함께 totalPages, totalRecords, hasNextPage가 포함된 .pageInfo이 있습니다. 응답은 postsByLocation 아래에 반환됩니다.

이 경로는 tag을 거부하므로, SDK는 0.5.3부터 하위 호환성을 위해 해당 인수를 허용하지만 실제 요청에는 절대 포함하지 않습니다. 태그 필터링이 필요한 경우 posts.bulk_list_for_location를 사용합니다.

Python

client.posts.list_for_location(    location_id: str | int,    *,    tag: str = "all",    page: int | None = None,    per_page: int | None = None,    filters: dict | None = None,    sort_fields: dict | None = None,) -> APIObject

Python

result = client.posts.list_for_location(16808, page=1, per_page=10)for post in result.records:  print(post.id, post.name)print(result.pageInfo.totalRecords)

`posts.bulk_retrieve`

일괄(여러 사업장) 캠페인의 사업장별 게시 상태와 분석 데이터를 조회합니다.

Python

client.posts.bulk_retrieve(bulk_post_id: str) -> APIObject

Python

bulk = client.posts.bulk_retrieve("QnVsa1Bvc3Q6OTk=")print(bulk.status)

`posts.bulk_list_for_location`

특정 사업장을 포함하는 일괄(여러 사업장) 캠페인 목록을 조회합니다. 매개변수와 결과 구조는 posts.list_for_location와 동일합니다.

Python

client.posts.bulk_list_for_location(    location_id: str | int,    *,    tag: str = "all",    page: int | None = None,    per_page: int | None = None,    filters: dict | None = None,    sort_fields: dict | None = None,) -> APIObject

Python

result = client.posts.bulk_list_for_location(16808, page=1, per_page=10)for campaign in result.records:  print(campaign.id, campaign.name)