Most recently created first. from and to apply to the scheduled time (to is exclusive). The member role sees only the posts of bots it can access. Scope: communities:read.
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
community_ids takes one target or up to 20; several targets are saved in one transaction (if one is invalid, none is created). Needs scheduled_at or publish_now. A post from the member role goes to admin approval (pending_approval) and isn't published even with publish_now. A content policy block returns 422 content_policy; flagged phrases and missing channel permissions are returned in warnings. A channel error during immediate publishing doesn't undo the record: the outcome is in the status and error fields of posts. In test mode the post doesn't go to Telegram and simulated is true. Use Idempotency-Key to avoid duplicates on retries. With a whatsapp block, a WhatsApp campaign draft is opened from the same content: it only uses an approved MARKETING template, only goes to opted-in people, and is sent after an admin approves it; it needs the write scope. If the WhatsApp part is invalid nothing is created (404 template_not_found, 400 template_not_allowed or template_params, 409 empty_audience or channel_not_configured, 502 channel_error). Scope: communities:write.
Optional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255
Body fields
Name
Type
Required
Description
community_ids
uuid[]
yes
items 1–20
text
string
yes
Up to 1024 characters on a post with an imagelen 1–4096
publish_now
boolean
no
topic_ids
object
no
Target topic in a forum group: community ID → topic ID
image_url
string | null
no
Public https addresslen ≤ 1000
button_text
string | null
no
len ≤ 64
button_url
string | null
no
https address; used with button_textlen ≤ 1000
silent
boolean
no
pin
boolean
no
repeat
enum
no
none | daily | weekly
scheduled_at
date-time
no
ISO 8601 instant with a time zone offset
whatsapp
object
no
whatsapp.bot_id
uuid
yes
WhatsApp bot
whatsapp.template_name
string
yes
A template approved by Meta, in the MARKETING category, without a media headerlen 1–512
whatsapp.template_language
string
yes
len 2–15
whatsapp.template_params
string[]
no
Header and body variables in order; line breaks become a single spaceitems ≤ 20
whatsapp.topic
string
no
Optional campaign topic; people who turned the topic off aren't in the audiencelen ≤ 40
Example request
curl -X POST "https://hiboty.com/api/v1/scheduled-posts" \
-H "Authorization: Bearer $HIBOTY_API_KEY" \
-H "Idempotency-Key: order-10482" \
-H "Content-Type: application/json" \
-d '{"community_ids":["3fa85f64-5717-4562-b3fc-2c963f66afa6"],"text":"Our new campaign has started!","button_text":"View","button_url":"https://ornek.com/kampanya","repeat":"none","scheduled_at":"2030-01-15T10:00:00+03:00"}'
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).template_not_allowed
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
404The record doesn't exist or this key can't access it (not_found).template_not_found
409The action isn't possible in this state; the code gives the reason.empty_audience
422Blocked by the content policy (content_policy).content_policy
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
502A channel or external service failed (channel_error).channel_error
The same range as the dashboard calendar: weeks starting on Monday, in the organization's time zone. Each day comes with its posts; a multi-target round is one item. Defaults to the current month. Scope: communities:read.
Scope
communities:read
SDK method
getPostCalendar · get_post_calendar
MCP tool
getPostCalendarread-only
Parameters
Name
Type
Required
Description
monthquery
string
no
YYYY-MM
Example request
curl -X GET "https://hiboty.com/api/v1/scheduled-posts/calendar" \
-H "Authorization: Bearer $HIBOTY_API_KEY"
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
404The record doesn't exist or this key can't access it (not_found).
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
Only posts in scheduled or pending_approval can be edited; once sending has started it returns 409 post_locked. Admins can edit any post, members only their own pending one; the status doesn't change, so a member's post stays pending. On a multi-target post all targets of the round change together. Validation and content policy are the same as on creation (422 content_policy). Scope: communities:write.
Scope
communities:write
SDK method
updateScheduledPost · update_scheduled_post
MCP tool
updateScheduledPost
Parameters
Name
Type
Required
Description
idpath
uuid
yes
ID
Body fields
Name
Type
Required
Description
text
string
no
len 1–4096
topic_ids
object
no
Target topic in a forum group: community ID → topic ID
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
404The record doesn't exist or this key can't access it (not_found).
409The action isn't possible in this state; the code gives the reason.post_locked
422Blocked by the content policy (content_policy).content_policy
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
Admins can cancel any post, members only their own pending one. On a multi-target post the unsent targets and later rounds of the series are canceled; sent targets don't change. If nothing is left to cancel it returns 409 post_locked. Scope: communities:write.
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
404The record doesn't exist or this key can't access it (not_found).
409The action isn't possible in this state; the code gives the reason.post_locked
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
On a multi-target post the round's scheduled targets are published and each target's outcome is in posts; targets that don't fit the time budget stay scheduled. A failed post or target is retried with this endpoint. For a single target, a channel error returns 502 channel_error, a policy block 422 content_policy, and a post that isn't scheduled 409 post_locked. In test mode nothing goes to Telegram. Needs admin permission. Scope: communities:write.
Optional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
404The record doesn't exist or this key can't access it (not_found).
409The action isn't possible in this state; the code gives the reason.post_locked
422Blocked by the content policy (content_policy).content_policy
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
502A channel or external service failed (channel_error).channel_error
The content is rechecked against the current policy (422 content_policy). If its time has passed it's published right away; a publishing error doesn't undo the approval and is returned in warnings. On a multi-target post all targets of the round are approved. If it isn't pending it returns 409 post_locked. Needs admin permission. Scope: communities:write.
Optional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
404The record doesn't exist or this key can't access it (not_found).
409The action isn't possible in this state; the code gives the reason.post_locked
422Blocked by the content policy (content_policy).content_policy
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
The reason is optional and is sent to the author. On a multi-target post all targets of the round are rejected. If it isn't pending it returns 409 post_locked. Needs admin permission. Scope: communities:write.
Optional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
404The record doesn't exist or this key can't access it (not_found).
409The action isn't possible in this state; the code gives the reason.post_locked
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
Only for a post or target in uncertain. Warning: the earlier attempt may have reached Telegram, so the message can appear twice; check the channel first. Other targets aren't touched. If it isn't uncertain it returns 409 post_locked; a channel error returns 502 channel_error. Needs admin permission. Scope: communities:write.
Optional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
404The record doesn't exist or this key can't access it (not_found).
409The action isn't possible in this state; the code gives the reason.post_locked
422Blocked by the content policy (content_policy).
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
502A channel or external service failed (channel_error).channel_error