Telegraph API

Telegraph API

TN Cole Varckin

Telegra.ph — это минималистский инструмент, который позволяет создавать посты и отправлять их в сеть всего одним щелчком. Telegraph-сообщения также получают красивый Instant View в Telegram.

Для поддержания базового интерфейса Telegram запустил @Telegraph бота для тех, кому требуются расширенные возможности. Этот бот поможет вам управлять вашими статьями на любом количестве устройств и получать статистику просмотра страниц.

Любой желающий может насладиться простотой Telegraph. Поэтому все разработчики могут использовать Telegraph API для создания ботов как @Telegraph или собственных приложений.

Все запросы к API должны быть отправлены через HTTPS и представлены в таком виде: https://api.telegra.ph/%method%.

Если присутствует Path параметр, вы также можете использовать эту форму: https://api.telegra.ph/%method%/%path%.

1. Методы

2. Типы

3. Content format


Доступные методы

Telegraph поддерживает GET и POST-методы протокола HTTP. Ответ содержит JSON-объект, который всегда имеет логическое поле ok. Если ok равен True, то запрос был успешным, и результат запроса может быть найден в поле result. Если запрос ok равен false, то ошибка объясняется в поле error (например, SHORT_NAME_REQUIRED). Все запросы должны быть сделаны с использованием UTF-8.

createAccount

Используйте этот метод, чтобы создать новый Telegraph-аккаунт. Большинству пользователей нужен только один аккаунт, но это может быть полезно для администраторов канала, которые хотели бы хранить отдельно имена авторов и ссылок на профили для каждого из каналов. В случае успеха возвращает объект Account с регулярными полями и дополнительными полями access_token.

  • short_name (String, 1-32 символов)

Обязательно. Имя аккаунта помогает пользователям с несколькими аккаунтами запомнить используемый аккаунт. Отображается для пользователя выше "Edit/Publish" на Telegra.ph, другие пользователи не видят этого имени.

  • author_name (String, 0-128 символов)

Имя автора по умолчанию используется при создании новых постов.

  • author_url (String, 0-512 символов)

По умолчанию ссылка на профиль открывается, когда пользователь нажимает на имя автора под заголовком. Можно использовать любую ссылку, необязательно профиль Telegram или канала.

Пример запроса
https://api.telegra.ph/createAccount?short_name=Sandbox&author_name=Anonymous

editAccountInfo

Используйте этот метод, чтобы обновить информацию о Telegraph-аккаунте. Проходят только те параметры, которые вы хотите изменить. В случае успеха возвращает объект Account с полями по умолчанию.

  • access_token (String)

Обязательно. Токен доступа Telegraph-аккаунта.

  • short_name (String, 1-32 символов)

Новое имя аккаунта.

  • author_name (String, 0-128 символов)

Новое имя автора, используется по умолчанию при создании новых постов.

  • author_url (String, 0-512 символов)

Новая ссылка на профиль, открывается по умолчанию, когда пользователь нажимает на имя автора под заголовком. Можно любую ссылку, необязательно в профиль Telegram или канала.

Пример запроса
https://api.telegra.ph/editAccountInfo?access_token=b968da509bb76866c35425099bc0989a5ec3b32997d55286c657e6994bbb&short_name=Sandbox&author_name=Anonymous

getAccountInfo

Используйте этот метод, чтобы получить информацию о Telegraph-аккаунте. Возвращает объект Account при успехе.

  • access_token (String)

Обязательно. Токен доступа Telegraph-аккаунта.

  • fields (Array of String, default = [“short_name”,“author_name”,“author_url”])

Возвращает список полей аккаунта. Доступные поля: short_name, author_name, author_url, auth_url, page_count.

Пример запроса
https://api.telegra.ph/getAccountInfo?access_token=b968da509bb76866c35425099bc0989a5ec3b32997d55286c657e6994bbb&fields=["short_name","page_count"]

revokeAccessToken

Используйте этот метод, чтобы отменить access_token и создать новый: например, если пользователь хочет сбросить все подключенные сессии, или есть основания полагать, что access_token был взломан. В случае успеха возвращает объект Account с новым access_token и по auth_url.

  • access_token (String)

Обязательно. Токен доступа Telegraph-аккаунта.

Пример запроса
https://api.telegra.ph/revokeAccessToken?access_token=b968da509bb76866c35425099bc0989a5ec3b32997d55286c657e6994bbb

createPage

Используйте этот метод, чтобы создать новую Telegraph-страницу. В случае успеха возвращает объект Page.

  • access_token (String)

Обязательно. Токен доступа Telegraph-аккаунта.

  • title (String, 1-256 символов)

Обязательно. Заголовок страницы.

  • author_name (String, 0-128 символов)

Имя автора отображается ниже заголовка статьи.

  • author_url (String, 0-512 символов)

Ссылка на профиль открывается, когда пользователь нажимает на имя автора под заголовком. Можно использовать любую ссылку, необязательно профиль Telegram или канала.

  • content (Массив Node, до 64 KB)

Обязательно. Content страницы. 

  • return_content (Boolean, по умолчанию = false)

Если True, то content поля будет возвращать объект Page (см.: Content format).

Пример запроса
https://api.telegra.ph/createPage?access_token=b968da509bb76866c35425099bc0989a5ec3b32997d55286c657e6994bbb&title=Sample+Page&author_name=Anonymous&content=[{"tag":"p","children":["Hello,+world!"]}]&return_content=true

editPage

Используйте этот метод, чтобы изменить Telegraph-страницу. В случае успеха возвращает объект Page.

  • access_token (String)

Обязательно. Токен доступа Telegraph-аккаунта.

  • path (String)

Обязательно. Ссылка на страницу.

  • title (String, 1-256 символов)

Обязательно. Заголовок страницы.

  • content (Массив Node, до 64 KB)

Обязательно. Content страницы.

  • author_name (String, 0-128 символов)

Имя автора отображается ниже заголовка статьи.

  • author_url (String, 0-512 символов)

Ссылка на профиль открывается, когда пользователь нажимает на имя автора под заголовком. Можно любую ссылку, необязательно в профиль Telegram или канала.

  • return_content (Boolean, по умолчанию = false)

Если True, то content поля будет возвращать объект Page.

Пример запроса
https://api.telegra.ph/editPage/Sample-Page-12-15?access_token=b968da509bb76866c35425099bc0989a5ec3b32997d55286c657e6994bbb&title=Sample+Page&author_name=Anonymous&content=[{"tag":"p","children":["Hello,+world!"]}]&return_content=true

getPage

Используйте этот метод, чтобы получить Telegraph-страницу. Возвращает объект Page при успехе.

  • path (String)

Обязательно. Ссылка к Telegraph-странице (Формат Title-12-31, т. е. все, что идет после http://telegra.ph/).

  • return_content (Boolean, по умолчанию = false)

Если True, то content поля будет возвращать объект Page.

Пример запроса
https://api.telegra.ph/getPage/Sample-Page-12-15?return_content=true

getPageList

Используйте этот метод, чтобы получить список страниц, относящихся к Telegraph-аккаунту. Возвращает объект PageList, отсортированный по недавно созданным страницам в первую очередь.

  • access_token (String)

Обязательно. Токен доступа Telegraph-аккаунта.

  • offset (Integer, по умолчанию = 0)

Возвращает порядковый номер первой странице.

  • limit (Integer, 0-200, по умолчанию = 50)

Ограничивает количество страниц, которые должны быть получены при запросе.

Пример запроса
https://api.telegra.ph/getPageList?access_token=b968da509bb76866c35425099bc0989a5ec3b32997d55286c657e6994bbb&limit=3

getViews

Используйте этот метод, чтобы получить статистику просмотров Telegraph статьи. Возвращает PageViews при успехе. По умолчанию будет возвращено общее количество просмотров страницы.

  • path (String)

Обязательно. Путь к Telegraph-странице (Формат Title-12-31, где 12 месяцев и 31 день, когда статья была впервые опубликована).

  • year (Integer, 2000-2100)

Обязательно, если прошел месяц. Если он будет принят, то возвращена будет статистика просмотров страницы за требуемый период.

  • month (Integer, 1-12)

Обязательно, если прошел день. Если он будет принят, то возвращена будет статистика просмотров страницы за требуемый месяц.

  • day (Integer, 1-31)

Обязательно, если прошел час. Если он будет принят, то возвращена будет статистика просмотров страницы за требуемый день.

  • hour (Integer, 0-24)

Если он будет принят, то возвращена будет статистика просмотров страницы за требуемый час.

Пример запроса
https://api.telegra.ph/getViews/Sample-Page-12-15?year=2016&month=12


Доступные типы

Все типы, используемые в запросе на Telegraph API, представлены в виде JSON-объектов. Необязательные поля могут быть не возвращены.

Account

Этот объект представляет Telegraph-аккаунт. 

  • short_name (String)

Имя аккаунта помогает пользователям с несколькими аккаунтами. Отображается для пользователя выше "Edit/Publish" на Telegra.ph, другие пользователи не видят этого имени.

  • author_name (String)

Имя автора по умолчанию используется при создании новых постов.

  • author_url (String)

Ссылка на профиль открывается, когда пользователь нажимает на имя автора под заголовком. Можно использовать любую ссылку, необязательно профиль Telegram или канала.

  • access_token (String)

Необязательно. Возвращается только при операции createAccount и revokeAccessToken. Токен доступа Telegraph-аккаунта.

  • auth_url (String)

Необязательно. URL для авторизации в браузере на telegra.ph и подключении его к Telegraph-аккаунту. Этот URL действителен только для одного использования, а так всего 5 минут.

  • page_count (Integer)

Необязательно. Количество страниц, принадлежащих к Telegraph-аккаунту.

PageList

Этот объект представляет список Telegraph-страниц, относящихся к аккаунту. Большинство недавно созданных статей.

  • total_count (Integer)

Общее количество страниц, относящихся к Telegraph-аккаунту.

  • pages (Массив Page)

Запрашиваемые страницы Telegraph-аккаунта.

Page

Этот объект представляет страницу на Telegraph.

  • path (String)

Путь к странице.

  • url (String)

URL страницы.

  • title (String)

Заголовок страницы.

  • description (String)

Описание страницы.

  • author_name (String)

Необязательно. Имя автора отображается под заголовком.

  • author_url (String)

Необязательно. Ссылка на профиль открывается, когда пользователь нажимает на имя автора под заголовком. Можно любую ссылку, не обязательно профиль Telegram или канала.

  • image_url (String)

Необязательно. URL изображения страницы.

  • content (Массив Node)

Необязательно. Content страницы.

  • views (Integer)

Статистика просмотров страницы.

  • can_edit (Boolean)

Необязательно. Возвращается только если access_token действительный. Правда если Telegraph-аккаунт может редактировать страницу.

PageViews

Этот объект представляет число просмотров страниц для Telegraph статьи.

  • views (Integer)

Статистика просмотров страницы.


Node

Этот абстрактный объект представляет собой DOM Node. Он может быть String, который представляет собой текстовый узел DOM или объект NodeElement.

NodeElement

Этот объект представляет собой узел dom-элементов.

  • tag (String)

Имя DOM элемента. Доступные метки: a, aside, b, blockquote, br, code, em, figcaption, figure, h3, h4, hr, i, iframe, img, li, ol, p, pre, s, strong, u, ul, video.

  • attrs (Object)

Необязательно. Атрибуты DOM элемента. Ключ объект представляет имя атрибута, значение атрибута. Доступны следующие атрибуты: href, src.

  • children (Массив Node)

Необязательно. Список дочерних узлов для DOM элементов.


Content format

Telegraph API использует формат DOM-based для представления содержимого страницы. Ниже приведен пример кода на JavaScript, который объясняет, как вы можете использовать его:

function domToNode(domNode) {
  if (domNode.nodeType == domNode.TEXT_NODE) {
    return domNode.data;
  }
  if (domNode.nodeType != domNode.ELEMENT_NODE) {
    return false;
  }
  var nodeElement = {};
  nodeElement.tag = domNode.tagName.toLowerCase();
  for (var i = 0; i < domNode.attributes.length; i++) {
    var attr = domNode.attributes[i];
    if (attr.name == 'href' || attr.name == 'src') {
      if (!nodeElement.attrs) {
        nodeElement.attrs = {};
      }
      nodeElement.attrs[attr.name] = attr.value;
    }
  }
  if (domNode.childNodes.length > 0) {
    nodeElement.children = [];
    for (var i = 0; i < domNode.childNodes.length; i++) {
      var child = domNode.childNodes[i];
      nodeElement.children.push(domToNode(child));
    }
  }
  return nodeElement;
}

function nodeToDom(node) {
  if (typeof node === 'string' || node instanceof String) {
    return document.createTextNode(node);
  }
  if (node.tag) {
    var domNode = document.createElement(node.tag);
    if (node.attrs) {
      for (var name in node.attrs) {
        var value = node.attrs[name];
        domNode.setAttribute(name, value);
      }
    }
  } else {
    var domNode = document.createDocumentFragment();
  }
  if (node.children) {
    for (var i = 0; i < node.children.length; i++) {
      var child = node.children[i];
      domNode.appendChild(nodeToDom(child));
    }
  }
  return domNode;
}

var article = document.getElementById('article');
var content = domToNode(article).children;
$.ajax('https://api.telegra.ph/createPage', {
  data: {
    access_token:   '%access_token%',
    title:          'Title of page',
    content:        JSON.stringify(content),
    return_content: true
  },
  type: 'POST',
  dataType: 'json',
  success: function(data) {
    if (data.content) {
      while (article.firstChild) {
        article.removeChild(article.firstChild);
      }
      article.appendChild(nodeToDom({children: data.content}));
    }
  }
});


Источник: http://telegra.ph/api

Report content on this page

Report Page

Please submit your DMCA takedown request to dmca@telegram.org