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.