GraphQL¶

"""Channel profile shown above the posts."""
type Channel {
  username: String!
  title: ParsedAndRaw!
  description: ParsedAndRaw
  avatar: String
  counters: Counters!

  """Header labels, e.g. `verified`."""
  labels: [String!]
}

"""Channel page: profile, posts and pagination."""
type ChannelBody {
  channel: Channel!
  content: ChannelContent!
  meta: Meta!
}

"""Posts of a channel page."""
type ChannelContent {
  posts: [Post!]!
}

"""Channel statistics as formatted by Telegram (e.g. `1.2M`)."""
type Counters {
  subscribers: String!
  photos: String
  videos: String
  files: String
  links: String
}

"""Publication time."""
type Date {
  """ISO-8601 timestamp with offset."""
  string: String!
  unix: Long!
}

"""Load posts newer (`after`) or older (`before`) than a position."""
enum Direction {
  after
  before
}

"""Duration of time-based media."""
type Duration {
  """Human-readable value as shown by Telegram, e.g. `2:30`."""
  formatted: String!

  """Duration in seconds."""
  raw: Int!
}

"""Kind of a formatting entity."""
enum EntityType {
  italic
  bold
  code
  spoiler
  strikethrough
  underline
  text_link
  url
  pre
  emoji
  animoji
  hashtag
}

"""A repost of the same story collapsed into a feed post."""
type FeedDuplicate {
  channel: String
  id: Int!
}

"""A feed post with its channel and ranking score."""
type FeedPost {
  id: Int!
  content: PostContent!
  footer: Footer!
  forwarded: Forwarded
  view: String!
  channel: Channel!

  """
  Ranking score (`_score` in the REST feed); the feed is in ranking order.
  """
  score: Float!

  """Reposts of the same story collapsed into this post (`_duplicates`)."""
  duplicates: [FeedDuplicate!]!

  """Subject shared with other feed posts (`_topic`), if any."""
  topic: FeedTopic
}

"""Subject a feed post shares with other posts of the feed."""
type FeedTopic {
  id: Int!
  keywords: [String!]!
}

"""Post metadata shown under the message."""
type Footer {
  views: String
  edited: Boolean
  author: ParsedAndRaw
  date: Date!
}

"""Original source of a forwarded post."""
type Forwarded {
  """Source channel or user; empty when the sender hides their name."""
  name: ParsedAndRaw!
  url: String

  """Signature shown next to the source, e.g. the bot that posted it."""
  author: ParsedAndRaw
}

"""Inline keyboard button."""
type InlineButton {
  title: String!
  url: String!
}

"""Integer that may exceed 32 bits (Unix timestamps)."""
scalar Long

"""Media attachment of a post."""
type MediaItem {
  url: String
  thumb: String

  """Encoded waveform of a voice message."""
  waves: String
  duration: Duration
  type: MediaType!

  """False when Telegram does not expose the file (e.g. a too large video)."""
  available: Boolean
}

"""Kind of a media attachment."""
enum MediaType {
  image
  video
  voice
  roundvideo
  sticker
  gif
}

"""Pagination metadata."""
type Meta {
  offset: Offset!
}

"""A batch of posts loaded relative to a position."""
type More {
  posts: [Post!]!
  meta: Meta!
}

"""Pagination cursors: pass them to `more` to load adjacent posts."""
type Offset {
  before: Int
  after: Int
}

"""Text in two forms: plain `string` and the original `html`."""
type ParsedAndRaw {
  string: String!
  html: String!
}

"""Poll attached to a post."""
type Poll {
  question: String!
  type: String
  votes: String
  options: [PollOption!]!
}

"""One answer option of a poll."""
type PollOption {
  name: String!
  percent: Int!
}

"""A channel post."""
type Post {
  id: Int!
  content: PostContent!
  footer: Footer!
  forwarded: Forwarded
  view: String!
}

"""Everything a post can contain."""
type PostContent {
  text: Text
  media: [MediaItem!]
  poll: Poll
  inline: [InlineButton!]
  reply: Reply
  preview_link: PreviewLink
  reacts: [Reaction!]
}

"""Channel preview."""
type Preview {
  """The requested channel username."""
  username: String!
  channel: PreviewChannel
}

"""Channel summary from the `t.me/<channel>` landing page."""
type PreviewChannel {
  title: String!
  subscribers: String!
  description: String
  avatar: String
  is_verified: Boolean!
}

"""Link preview card generated by Telegram."""
type PreviewLink {
  title: String
  url: String!
  site_name: String
  description: ParsedAndRaw
  thumb: String
}

"""Read-only access to public Telegram channels."""
type Query {
  """
  Channel profile, its latest posts (or posts around `position`) and pagination. REST: `GET /v1/body/{channel}`.
  """
  body(
    """Channel username, e.g. `durov`."""
    channel: String!

    """Open the page around this post ID."""
    position: Int = null
  ): ChannelBody

  """
  Posts newer or older than `position` (anchor excluded); use `meta.offset` to keep paginating. REST: `GET /v1/more/{channel}/{direction}/{position}`.
  """
  more(
    """Channel username, e.g. `durov`."""
    channel: String!
    direction: Direction!

    """Anchor post ID."""
    position: Int!
  ): More

  """A single post. REST: `GET /v1/post/{channel}/{identifier}`."""
  post(
    """Channel username, e.g. `durov`."""
    channel: String!

    """Post ID."""
    id: Int!
  ): Post

  """
  Short channel summary: title, subscribers, description, avatar. REST: `GET /v1/preview/{channel}`. Requires `ENABLE_PREVIEWS`.
  """
  preview(
    """Channel username, e.g. `durov`."""
    channel: String!
  ): Preview

  """
  Previews of several channels, fetched in parallel; unknown channels are omitted. REST: `POST /v1/previews`. Requires `ENABLE_PREVIEWS`.
  """
  previews(
    """1 to 100 channel usernames."""
    channels: [String!]!
  ): [Preview!]

  """
  Posts of several channels ranked by score, best first. REST: `POST /v1/feed`. Requires `ENABLE_FEED`.
  """
  feed(
    """1 to 100 channel usernames."""
    channels: [String!]!
  ): [FeedPost!]
}

"""One reaction counter of a post."""
type Reaction {
  count: String!
  type: ReactionType!
  emoji: String
  emoji_id: String
  emoji_image: String
}

"""Kind of a reaction."""
enum ReactionType {
  telegram_stars
  emoji
  custom_emoji
}

"""The message this post replies to."""
type Reply {
  cover: String
  name: ParsedAndRaw!
  text: ParsedAndRaw!
  to_message: Int!
}

"""Post text with optional formatting entities."""
type Text {
  string: String!
  html: String!
  entities: [TextEntity!]
}

"""Formatting entity inside a post text; offsets refer to `string`."""
type TextEntity {
  offset: Int!
  length: Int!
  type: EntityType!
  language: String
  url: String
}