Publisher API: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

Connect a social channel

A site owner wants to connect a new social channel so they can publish to it, without leaving your app for the dashboard.

To connect a channel:

1. Call Get Connect Url with the channelName to retrieve the channel's OAuth authorization URL.
2. Surface the URL to the site owner and have them open it and authorize the channel in their browser. The channel's OAuth redirect completes the connection server-side.
3. Poll Get Long Lived Token Status with the channelName until the status is VALID, which confirms the channel is connected.
4. To disconnect the channel later, call Disconnect with the channelName.

Connect a channel and publish an AI-generated post

A site owner wants to connect a channel, generate a post caption and image with AI, and publish it, all in one flow.

To connect a channel and publish an AI-generated post:

1. Call Get Long Lived Token Status with the channelName to check whether the channel is already connected.
2. If the status isn't VALID, connect the channel: call Get Connect Url with the channelName, surface the returned OAuth authorization URL to the site owner to authorize in their browser (the OAuth redirect completes the connection server-side), then poll Get Long Lived Token Status until the status is VALID.
3. Call Generate Text with a prompt describing the post to get caption suggestions.
4. Call Generate Image with a prompt and a source image (a source image is required, since the method edits an existing image rather than generating one from a text prompt alone) to start image generation, then poll Get Generated Image with the returned executionId until the status is READY to get the image's imageUrl and fileId.
5. Call Create Draft Item with the chosen caption and the generated image. The response includes the draft's id.
6. Call Publish Item By ID with the draft's id to publish it immediately, or include a scheduledDate to schedule it.

Create and publish a post

A site owner wants to publish a post to one of their connected social channels.

To create and publish a post:

1. Call List Accounts for the channel to retrieve the connected account's id.
2. Call Get Feature Data with PUBLISH_POST to confirm the site can publish and has remaining quota.
3. Call Create Draft Item with the post's channel, type, and content. The type and content must match a combination the channel supports. The response includes the draft's id.
4. Call Publish Item By ID with the draft's id to publish it immediately. The published post appears on the site's Social Media Marketing page in the dashboard.

Schedule a post for a future date

A site owner wants to prepare a post now and have it published automatically at a later time.

To schedule a post:

1. Call Create Draft Item with the post's channel, type, and content. The response includes the draft's id.
2. Call Publish Item By ID with the draft's id and a scheduledDate. The post is published at that date with a status of SCHEDULED.

Reschedule or cancel a scheduled post

A site owner wants to change the publish date of a scheduled post, or stop it from being published.

To reschedule or cancel a scheduled post:

1. Call Query Items to find the scheduled post and get its id from the results.
2. To move the post to a different date, call Reschedule Item with the id and the new scheduledDate. To stop it from being published, call Cancel Scheduled Item with the id.

Generate post content and publish it

A site owner wants to create a post from one of their site's assets, such as a product, without writing the content themselves.

To generate post content and publish it:

1. Get the asset's ID from the app that owns it. For example, call Query Products for a STORES_PRODUCT, or Query Posts for a BLOG_POST.
2. Call Generate Post Data with a single site asset (its id and type), a free-text userInput, or both, and optionally the channels to generate for. Supported asset types are STORES_PRODUCT, STORES_CATEGORY, STORES_COUPON, BLOG_POST, EVENT, and BOOKINGS_SERVICE. Only one asset is supported per call. The response returns ready-to-use content for each requested channel: image posts for Instagram, Facebook, LinkedIn, Pinterest, Google Business Profile, and TikTok. It doesn't return YouTube content or story and video formats.
3. Call Create Draft Item with the generated content for the channel you want to post to. The response includes the draft's id.
4. Call Publish Item By ID with the draft's id to publish it, or include a scheduledDate to schedule it.

Generate a caption for a post

A site owner wants to create a caption with AI to use in a post, rather than generate a full post.

To generate content and publish a post with it:

1. Call Generate Text with a prompt describing the post to generate caption suggestions.
2. Call Create Draft Item with the generated caption as the post's content. The response includes the draft's id.
3. Call Publish Item By ID with the draft's id to publish it, or include a scheduledDate to schedule it.

Find a site's scheduled posts

A site owner wants to see what's queued to go out, so they can confirm a post was scheduled before moving on.

To find a site's scheduled posts:

1. Call Query Items with filter set to {"status": "SCHEDULED"}. To narrow the results to one channel, add channel, and to narrow them to one format, add type.
2. Read the scheduled date of each returned item from schedulingInfo.scheduledDate.
3. Check the status of the returned items before treating the result as the site's schedule. An unsupported filter field is ignored rather than rejected, so a filter that names the wrong field returns every item instead of an error.

Publish a multi-frame story

A site owner has a story draft made up of several images and wants to publish every frame.

To publish a multi-frame story:

1. Call Query Items to find the story draft, and get its id from the results. A multi-frame story is an item whose type is STORY and whose media list holds more than one media item.
2. Call Publish Multi Story Draft with the draft's id, or include schedulingInfo.scheduledDate to schedule the sequence. Each frame is published as its own story item, in media order.
3. Check results in the response. Each entry reports one frame. If any frame failed, the draft is kept so you can fix the problem and call the method again. Frames that already published are skipped on the retry.