Marketing Plan 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.

Generate a marketing plan and publish its posts

The core flow: generate a plan for a site, then schedule its posts for publishing.

To generate a plan and publish its posts:

1. Call Generate Marketing Plan. The response returns a status of GENERATING.
2. Poll Get Social Marketing Plan until status is ACTIVE. The response contains the plan's marketingActivities, and the near-term activities already include generated posts in their items.
3. Collect the IDs of the items whose status is DRAFT from the activities you want to publish.
4. Call Schedule Drafts with those IDs to schedule the posts for publishing. Note that ScheduleDrafts only schedules drafts for channels the site has connected through the Publisher; drafts for unconnected channels are left as drafts.

Tailor the plan with marketing settings

Before generating, configure the site's marketing preferences so the AI produces a plan that matches the brand's goal, voice, and channels.

To tailor and generate a plan:

1. Optionally, call Get Plan Goal Options and Get Point Of View Options to retrieve the selectable values for those settings.
2. Call Upsert Marketing Settings with the chosen goal, social channels, point of view, posting frequency, and other preferences.
3. Call Generate Marketing Plan. The response returns a status of GENERATING.
4. Poll Get Social Marketing Plan until status is ACTIVE. The generated activities and posts reflect the configured settings.

Plan around a custom calendar event

Add an event, such as a seasonal sale or product launch, so the AI builds activities around it.

To plan around an event:

1. Call Create Event with the event's name and date. For a repeating event, set a recurring rule instead of a date.
2. Call Generate Marketing Plan, or Regenerate Marketing Plan if the site already has a plan. The response returns a status of GENERATING.
3. Poll Get Social Marketing Plan until status is ACTIVE. The plan's activities account for the event.

Generate and schedule posts for more activities

When a plan is generated, posts are created automatically only for the near-term activities. Use this flow to generate posts for the remaining activities and schedule them.

To generate and schedule more posts:

1. Call Get Social Marketing Plan and note the IDs of the activities that don't yet have posts.
2. Call Generate Social Posts with those activity IDs. The response returns immediately while generation continues in the background.
3. Poll Get Marketing Activity Posts for those activities until the posts appear.
4. Collect the IDs of the items whose status is DRAFT.
5. Call Schedule Drafts with those IDs to schedule them for publishing. Note that ScheduleDrafts only schedules drafts for channels the site has connected through the Publisher; drafts for unconnected channels are left as drafts.

Publish an activity's story

An activity in the plan can carry a story alongside its posts. This flow covers finding that story and publishing every one of its frames.

To publish an activity's story:

1. Call Get Marketing Activity Posts for the activity and find the item whose type is STORY. Not every activity has one.
2. Note that item's id and the number of media items in its media list. Each media item is one frame.
3. Call Publish Multi Story Draft in the Publisher API with that id. Each frame is published as its own story.

Replace a frame in an activity's story

A site owner likes a generated story but wants to swap out one of its images, without regenerating the rest.

To replace a single frame:

1. Call Get Marketing Activity Posts for the activity and find the item whose type is STORY.
2. Identify the position of the frame to replace in that item's media list. Positions are zero based.
3. Call Update Marketing Activity Stories Media with the activity's ID, the new mediaUrl and mediaType, and that position as mediaIndex. The story's other frames are left unchanged.