HighLevel: Create a new item in the queue

← Social planner operations · Get started

Operation gohighlevel.createqueueitem

Provider route: POST /social-media-posting/category/queues/{queueId}/create/item. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/gohighlevel with npm, or alter-sdk-gohighlevel with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { HighLevelIntegration } from "@alter-ai/gohighlevel";

async function execute(input: Parameters<HighLevelIntegration["socialPlanner"]["createQueueItem"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new HighLevelIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.socialPlanner.createQueueItem(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_gohighlevel import HighLevelIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = HighLevelIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.social_planner.create_queue_item(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.queueId	string	Required within parent
body	Model	Required within parent	Expand Create a new item in the queue — request body — body

Referenced models: Create a new item in the queue — request body — body

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Create a new item in the queue — response body

Referenced models: Create a new item in the queue — response body

Schemas

36 more schemas are linked from the tables above, on the schema pages.

Create a new item in the queue — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
directToQueue	boolean	Optional	When true, creates the queue item directly without requiring an edit session, even for active/paused queues. The order field is ignored and the item position is determined by the queue's prioritizeNewContent setting: if true, the item is added to the top of the queue; if false, it is added to the bottom.
locationId	string	Required within parent	Location ID
modifiedPostPayload	JSON	Optional	New post details
modifiedPostPayload (allOf 1)	Model	All variants apply	Expand Update an item in a queue — request body — body modified Post Payload account Ids, apply Watermark, category Id, created By, facebook Post Details, follow Up Comment, gmb Post Details, instagram Post Details, linkedin Post Details, location Id, media, og Tags Details, pinterest Post Details, post Approval Details, schedule Date, schedule Time Updated, selected Best Time, status, summary, tags, tiktok Post Details, type, user Id, youtube Post Details
order	JSON	Optional	Order for the new item in the queue (cyclic-aware). Accepts: - A number: explicit order value calculated by FE as midpoint between adjacent items - "top": place at cyclic top (first to be scheduled next) - "bottom": place at cyclic bottom (last to be scheduled) For positions between items, FE calculates: Math.floor((prevItem.order + nextItem.order) / 2) Defaults to end if not provided. Note: This field is ignored when directToQueue is true - the order will be automatically calculated based on the queue's prioritizeNewContent setting.
order (oneOf 1)	number	Alternative
order (oneOf 2)	string	Alternative
primaryImage	string	Optional	Primary media URL (image) for the post. Falls back to modifiedPostPayload.primaryImage if not set.
sessionId	string	Optional	Edit session ID
variations	array	Optional	Variations
variations[]	Model	Each item	Expand Update an item in a queue — request body — body variations item

Referenced models: Update an item in a queue — request body — body modified Post Payload account Ids, apply Watermark, category Id, created By, facebook Post Details, follow Up Comment, gmb Post Details, instagram Post Details, linkedin Post Details, location Id, media, og Tags Details, pinterest Post Details, post Approval Details, schedule Date, schedule Time Updated, selected Best Time, status, summary, tags, tiktok Post Details, type, user Id, youtube Post Details, Update an item in a queue — request body — body variations item

Create a new item in the queue — response body

Field	Type	Presence	Description and constraints
$	object	Root
results	Model	Required within parent	Expand Create a new item in the queue — response body — results
statusCode	JSON	Required within parent
statusCode (anyOf 1)	number	Alternative
statusCode (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
success	boolean	Required within parent
traceId	string	Optional

Referenced models: Create a new item in the queue — response body — results

Update an item in a queue — request body — body variations item

Field	Type	Presence	Description and constraints
$	object	Root
content	string	Optional	The text content of the variation.
mentions	array	Optional	Platform-specific mentions within the content (e.g., @username references).
mentions[]	object	Each item
ogTags	JSON	Optional	Open Graph tags for link previews.
ogTags (allOf 1)	Model	All variants apply	Expand Update an item in a queue — request body — body variations item og Tags meta Image, meta Link, og Title

Referenced models: Update an item in a queue — request body — body variations item og Tags meta Image, meta Link, og Title

Create a new item in the queue — response body — results

Field	Type	Presence	Description and constraints
$	object	Root
message	string	Optional	A message indicating the result of the operation.
queueItem	JSON	Optional	The newly created queue item
queueItem (allOf 1)	Model	All variants apply	Expand Clone a queue item — response body — results queue Item id, created At, current Variation, deleted, errors, last Scheduled Time, location Id, modified Post Payload, order, parent Post Id, post Id, primary Image, queue Id, updated At, variations

Referenced models: Clone a queue item — response body — results queue Item id, created At, current Variation, deleted, errors, last Scheduled Time, location Id, modified Post Payload, order, parent Post Id, post Id, primary Image, queue Id, updated At, variations

Edit post — request body — body / facebookPostDetails / type: post, story, reel

Field	Type	Presence	Description and constraints
$	object	Root
textFormatPresetId	string	Optional	Facebook background preset ID for text-only feed posts. **Facebook `post` only** — not `story` or `reel`. Ignored when media is attached; `metaLink` is omitted on publish. **Validations** — request returns `400` if violated: - Must be a valid preset ID from the [Facebook text background preset reference](https://help.leadconnectorhq.com/support/solutions/articles/155000008005-facebook-text-background-posts-preset-reference). Empty strings, whitespace-only values, and `null` are rejected. - When set, `summary` must be 130 characters or fewer.
type	string	Required within parent	Facebook post format type. **Available Types:** - `post` - Standard feed post (images, videos, text) - `story` - 24-hour temporary story - `reel` - Short-form vertical video **Restrictions:** - Reels: Require exactly 1 video, not supported on Groups - Stories: Captions not supported One of: post, story, reel

Edit post — request body — body / gmbPostDetails / actionType: none, order, book, shop, learn more, call, sign up, gmb Event Type: STANDARD, EVENT, OFFER

Field	Type	Presence	Description and constraints
$	object	Root
actionType	string	Optional	Call-to-action button type for the post. **Available Actions:** - `none` - No action button - `order` - Order online - `book` - Book appointment - `shop` - Shop now - `learn_more` - Learn more - `call` - Call now (no URL required) - `sign_up` - Sign up **Note:** All actions except `none` and `call` require a `url`. One of: none, order, book, shop, learn_more, call, sign_up
couponCode	string	Optional	Promotional coupon code. Required for OFFER posts.
endDate	JSON	Optional	End date and time for EVENT or OFFER posts. **Required:** When `gmbEventType` is `EVENT` or `OFFER`. **Validation:** Must be after `startDate`. **Structure:** - `endDate`: { year, month, day } - `endTime`: { hours, minutes, seconds }
endDate (allOf 1)	Model	All variants apply	Expand Edit post — request body — body / gmbPostDetails / actionType: none, order, book, shop, learn more, call, sign up, gmb Event Type: STANDARD, EVENT, OFFER end Date end Date, end Time
gmbEventType	string	Required within parent	Google My Business post type. **Available Types:** - `STANDARD` - Regular update post (What's New) - `EVENT` - Event announcement with dates and title - `OFFER` - Promotional offer with coupon and redemption details **Required fields by type:** - STANDARD: None additional - EVENT: `title`, `startDate`, `endDate` - OFFER: `offerTitle`, `startDate`, `endDate`, `termsConditions`, `couponCode`, `redeemOnlineUrl` One of: STANDARD, EVENT, OFFER
offerTitle	string	Optional	Offer title. Required when `gmbEventType` is `OFFER`.
redeemOnlineUrl	string	Optional	URL where customers can redeem the offer online. Required for OFFER posts.
startDate	JSON	Optional	Start date and time for EVENT or OFFER posts. **Required:** When `gmbEventType` is `EVENT` or `OFFER`. **Structure:** - `startDate`: { year, month, day } - `startTime`: { hours, minutes, seconds }
startDate (allOf 1)	Model	All variants apply	Expand Edit post — request body — body / gmbPostDetails / actionType: none, order, book, shop, learn more, call, sign up, gmb Event Type: STANDARD, EVENT, OFFER start Date start Date, start Time
termsConditions	string	Optional	URL to terms and conditions page. Required for OFFER posts.
title	string	Optional	Event title. Required when `gmbEventType` is `EVENT`. **Max length:** 58 characters
url	string	Optional	Call-to-action URL. Required when `actionType` is set (except `none` and `call`). **Required for:** STANDARD and EVENT posts with actionType other than `none` or `call`.

Referenced models: Edit post — request body — body / gmbPostDetails / actionType: none, order, book, shop, learn more, call, sign up, gmb Event Type: STANDARD, EVENT, OFFER end Date end Date, end Time, Edit post — request body — body / gmbPostDetails / actionType: none, order, book, shop, learn more, call, sign up, gmb Event Type: STANDARD, EVENT, OFFER start Date start Date, start Time

Update an item in a queue — request body — body variations item og Tags meta Image, meta Link, og Title

Field	Type	Presence	Description and constraints
$	object	Root
metaImage	object	Optional	URL of the image to display in link preview.
metaLink	object	Optional	The canonical URL of the content for link preview.
ogTitle	object	Optional	Title to display in link preview.

Policy, approvals and errors

SDK function policy ID: gohighlevel.createqueueitem. Catalog operation: createQueueItem. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Required provider scopes: ["socialplanner/category.write"]

Pinned headers: {"Version": "v3"}

Official provider source