Schedule Telegram Posts via API

Platforms

Schedule posts to Telegram channels and groups

Mutation

Use the scheduleTelegramPost mutation to schedule posts to Telegram channels and groups:

Mutation

mutation ScheduleTelegramPost($input: ScheduleTelegramPostInput!) {
  scheduleTelegramPost(input: $input) {
    success
    errors {
      field
      message
    }
    post {
      id
      socialAccount {
        id
        username
      }
      publishingStatus
      text
      disableLinkPreview
      linkPreviewSize
      disableNotification
      pinAfterPublishing
      protectContent
      mediaSpoiler
      captionAboveMedia
      paidStarCount
      buttons {
        text
        url
      }
      gallery {
        id
        galleryMediaSet {
          id
          media {
            url
            mimeType
          }
        }
      }
      submissions {
        id
        postAt
      }
    }
  }
}

The username of the connected Telegram channel or group to post to, without the @. Private chats have no @username, so their numeric chat ID (e.g. -1001234567890) is used as the username instead.

schedulingMode

SchedulingModeType

How the post date is decided. Options: SPECIFIC_TIME, QUEUE_NEXT (default: SPECIFIC_TIME). Only accepted when scheduling a new post. See Scheduling at the Next Open Slot.

text

String

The message text (max 4,096 characters), or the caption when media is attached (max 1,024 characters). Plain text is published as typed and links are clickable automatically. To format text, use HTML with the tags Telegram supports (see Formatting). Limits count the visible characters. Required unless media is attached.

media

[SimpleMediaInput]

Media files to attach to the post: up to 10 photos and videos (sent as an album), or a single GIF. Each item references a file by id, name, or url. See Attaching Media. Only supported when scheduling new posts, not when updating existing ones.

disableLinkPreview

Boolean

Do not show a preview for the links in the message (default: false)

linkPreviewSize

TelegramLinkPreviewSize

How the preview of the first link shows its image. Options: DEFAULT, LARGE, SMALL (default: DEFAULT). Applies to text posts only, since media captions never show link previews.

mediaSpoiler

Boolean

Blur the attached photos and videos until they are tapped (default: false)

captionAboveMedia

Boolean

Show the text above the attached photos and videos instead of below them (default: false)

paidStarCount

Int

Publish the media as paid media: subscribers see it blurred until they pay this many Telegram Stars (1 to 25,000). In a channel the Stars are credited to the channel's balance; in a group, Telegram credits them to the bot's balance. Photos and videos only, no GIFs. 0 or omitted publishes the media normally (default: 0). See Paid media.

buttons

[TelegramButtonInput!]

Up to 10 link buttons shown under the message, one per row. Each button has a text label (max 64 characters) and an https://, http:// or tg://url. Not available on albums, unless the album is paid media.

disableNotification

Boolean

Send the message silently, without a notification sound (default: false)

pinAfterPublishing

Boolean

Pin the message in the chat right after it is published. In a channel, the bot needs the "Manage Messages" permission; in a group, it must be an administrator with the "Pin Messages" permission (default: false)

protectContent

Boolean

Prevent the message from being forwarded or saved (default: false)

submissions

[TelegramPostSubmissionInputType!]! required

Array of submissions defining when to post (minimum 1 submission)

publishingStatus

PublishingStatusType

Publishing status. Options: READY_TO_PUBLISH, DRAFT (default: READY_TO_PUBLISH)

postTags

[ID!]

Array of post tag IDs to organize your content. See Post Tags.

ID of existing post when updating (only for updates)

TelegramPostSubmissionInputType

Each submission defines a specific posting schedule:

postAt

DateTime

When to publish the post (must be in the future). Required unless you pass schedulingMode: QUEUE_NEXT on the post when scheduling a new one, or the post is a draft. See Drafts without a date.

ID of existing submission when updating (only for updates)

Examples

Simple Telegram Post

Schedule a text post with a link. Telegram makes the link clickable and shows a preview for it.

{
  "input": {
    "username": "mychannel",
    "text": "Our September update is live! Read what's new: https://example.com/september-update",
    "submissions": [
      {
        "postAt": "2026-10-01T09:00:00Z"
      }
    ]
  }
}

Silent Post without a Link Preview

{
  "input": {
    "username": "mychannel",
    "text": "Reminder: the community call starts in one hour. Join here: https://example.com/call",
    "disableLinkPreview": true,
    "disableNotification": true,
    "submissions": [
      {
        "postAt": "2026-10-01T16:00:00Z"
      }
    ]
  }
}

Telegram Album with a Caption

Format the text with Telegram's HTML tags and add link buttons under the post. Paragraphs (<p>) become line breaks, and the character limit counts the text readers see.

{
  "input": {
    "username": "mychannel",
    "text": "<p><b>Big news:</b> our September update is live.</p><p>Read the <a href=\"https://example.com/september-update\">full changelog</a>, or reveal the <span class=\"tg-spoiler\">surprise feature</span>.</p>",
    "linkPreviewSize": "LARGE",
    "buttons": [
      {"text": "Read the update", "url": "https://example.com/september-update"},
      {"text": "Get support", "url": "https://example.com/support"}
    ],
    "submissions": [{"postAt": "2026-10-01T09:00:00Z"}]
  }
}

Charge Telegram Stars for the media. Subscribers see the photos and videos blurred until they pay, and the caption and buttons stay visible.

{
  "input": {
    "username": "mychannel",
    "text": "Behind the scenes of this week's shoot 🎬",
    "media": [{"name": "shoot-1.jpg"}, {"name": "shoot-2.mp4"}],
    "paidStarCount": 50,
    "buttons": [{"text": "More exclusives", "url": "https://example.com/exclusives"}],
    "submissions": [{"postAt": "2026-10-01T09:00:00Z"}]
  }
}

Attach up to 10 photos and videos. The text is used as the album caption (max 1,024 characters).

{
  "input": {
    "username": "mychannel",
    "text": "Highlights from this week's photo walk 📸",
    "media": [
      { "url": "https://example.com/photo-1.jpg" },
      { "url": "https://example.com/photo-2.jpg" },
      { "name": "photo-walk-video.mp4" }
    ],
    "submissions": [
      {
        "postAt": "2026-10-02T12:00:00Z"
      }
    ]
  }
}

Pinned Announcement

Pin the message after it is published. In a channel, the bot needs the "Manage Messages" permission; in a group, it must be an administrator with the "Pin Messages" permission.

{
  "input": {
    "username": "-1001234567890",
    "text": "📌 Rules of the group: be kind, stay on topic, and have fun.",
    "pinAfterPublishing": true,
    "protectContent": true,
    "submissions": [
      {
        "postAt": "2026-10-03T08:00:00Z"
      }
    ]
  }
}

Response Types

Success Response

{
  "data": {
    "scheduleTelegramPost": {
      "success": true,
      "errors": [],
      "post": {
        "id": "123",
        "socialAccount": {
          "id": "456",
          "username": "mychannel"
        },
        "publishingStatus": "READY_TO_PUBLISH",
        "text": "Our September update is live! Read what's new: https://example.com/september-update",
        "disableLinkPreview": false,
        "linkPreviewSize": "DEFAULT",
        "disableNotification": false,
        "pinAfterPublishing": false,
        "protectContent": false,
        "mediaSpoiler": false,
        "captionAboveMedia": false,
        "paidStarCount": 0,
        "buttons": [],
        "gallery": null,
        "submissions": [
          {
            "id": "789",
            "postAt": "2026-10-01T09:00:00Z"
          }
        ]
      }
    }
  }
}

Error Response

{
  "data": {
    "scheduleTelegramPost": {
      "success": false,
      "errors": [
        {
          "field": "text",
          "message": "Telegram limits captions to 1,024 characters when media is attached."
        }
      ],
      "post": null
    }
  }
}

Updating a Post

To update an existing scheduled post, use the same input type with the updateScheduledTelegramPost mutation and include the post id:

Mutation

mutation UpdateScheduledTelegramPost($input: ScheduleTelegramPostInput!) {
  updateScheduledTelegramPost(input: $input) {
    success
    errors {
      field
      message
    }
    post {
      id
    }
  }
}

{
  "input": {
    "id": "12345",
    "username": "mychannel",
    "text": "Updated Telegram post!",
    "submissions": [{"id": "789", "postAt": "2026-10-01T15:30:00Z"}]
  }
}

The update mutation uses the same input type as the create mutation. Include the id field to specify which post to update. Only scheduled posts that have not been published yet can be updated.

Formatting

Plain text is published exactly as typed. To format a post, send text as HTML using only the tags Telegram supports:

Formatting	Tags
Bold, italic, underline, strikethrough	`<b>`, `<i>`, `<u>`, `<s>` (`<strong>`, `<em>`, `<ins>`, `<del>` also work)
Spoiler (hidden until tapped)	`<span class="tg-spoiler">` or `<tg-spoiler>`
Link	`<a href="https://...">`
Code	`<code>` inline, `<pre>` for blocks
Quote	`<blockquote>`
Line breaks	`<p>` paragraphs or `<br>`

Escape <, > and & in formatted text as <, > and &. Other tags are removed and their text is kept. The 4,096 and 1,024 character limits count the visible text only.

Paid media

Set paidStarCount to publish the attached photos and videos as paid media. Telegram shows them blurred with the price, and each subscriber who pays that many Stars unlocks them permanently. The Stars are credited to the channel's balance, where the channel owner manages them in Telegram. When paid media is posted to a group, Telegram credits the Stars to the bot's balance instead. Paid media is one message however many items it holds, so it can carry a caption of up to 1,024 characters and link buttons. GIFs can't be paid media, and Telegram does not report channel purchases to bots, so Postpone can't show earnings.

Validation Rules

Text Length: Maximum 4,096 characters, or 1,024 characters when media is attached, counting the visible text in UTF-16 code units as Telegram does (most emoji count as two)
Buttons: Up to 10 buttons with a label of at most 64 characters and an https://, http:// or tg:// URL; not allowed on albums, unless the album is paid media
Paid media: paidStarCount between 1 and 25,000 requires at least one photo or video and no GIFs
Media: Up to 10 photos (max 10MB each) and videos (max 50MB each) as an album, or a single GIF (max 50MB). Any image or video format Postpone accepts can be scheduled: images are converted to JPEG and videos to MP4 when the post is published
Images: Width plus height must not exceed 10,000 pixels, with a width to height ratio of at most 20
Pinning: pinAfterPublishing requires the bot to be allowed to pin in the chat ("Manage Messages" in a channel, "Pin Messages" as a group administrator)
Scheduling: Posts must be scheduled for future dates only
Account Limits: Respects your plan's monthly post limits

Common Errors

Tumblr

Schedule posts to Tumblr blogs

Introduction

Query analytics data and performance metrics for your social media posts.