<WRAP apidoc/>

====== @amperka/telegram ======

Библиотека для работы с мессенджером [[https://telegram.org/|telegram]].

Позволяет использовать сервис для управления Iskra JS: управление умным домом, вывод информации с датчиков, отправка уведомлений на телефон.

<code javascript>
var serial = PrimarySerial;
serial.setup(115200);

var bot = require('@amperka/telegram').create('-УКАЖИТЕ_ЗДЕСЬ_СВОЙ_API_ТОКЕН-');

bot.on('text', msg => {
  let fromId = msg.from.id;
  let firstName = msg.from.first_name;
  return bot.sendMessage(fromId, 'Welcome,'+firstName+'!');
});

var wifi = require('@amperka/wifi').connect(serial, function(err) {
  wifi.reset(function(err) {
    wifi.connect(SSID, PSWD, function(err) {
      bot.connect();
    });
  });
});
</code>

===== Функции модуля =====

func:: create(options)

Создаёт новый объект Telegram. Параметр ''options'' — объект, содержащий поля ''token'' и ''polling''. Поле ''token'' должно содержать токен, [[https://core.telegram.org/bots#6-botfather|выданный]] сервисом Телеграмм. Параметр ''options'' может содержать необязательные поля:
  * ''interval: 1000'' — Период опроса сервера на наличие новых сообщений (в миллисекундах).
  * ''timeout: 0'' — Время удержания соединения с сервером в ожидании ответа о новых сообщениях (0 — short polling, 0< — long polling).
  * ''limit: 1'' — Лимит новых сообщений для одного запроса в диапазоне от 1 до 100.
  * ''retryTimeout: 5000'' — Ограничение времени переподключения (в миллисекундах).

<code javascript>
var bot = require('telegram').create({
  token: '-УКАЖИТЕ_ЗДЕСЬ_СВОЙ_API_ТОКЕН-', // Обязательное. API токен Телеграм-бота
  polling: { // Необязательное
    interval: 1000,
    timeout: 0,
    limit: 1,
    retryTimeout: 5000
  }
});
</code>
class:: Telegram

Класс для работы с Telegram-ботом. Для создания экземпляра используйте функцию ''create''.

func:: Telegram.connect()

Функция запускает опрос сервиса Telegram на наличие новых сообщений.

<code javascript>
bot.connect();
</code>

func:: Telegram.disconnect()
Функция прекращает получение обновлений.

func:: Telegram.keyboard([array of arrays], {resize, once, selective})
Функция создаёт объект-клавиатуру, который может быть передан в качестве ''markup'' для функций ''sendMessage'' и ''sendLocation''.
  * ''keyboard'' — массив строк кнопок, где каждая строка представлена массивом объектов-кнопок.
  * ''resize'' — если ''true'', клавиатура изменит свой вертикальный размер для оптимального отображения. Значение по умолчанию — ''false'' — оставляет размер клавиатуры стандартного размера.
  * ''once'' — если ''true'', клавиатура скроется сразу после первого использования, но будет по-прежнему доступна для пользователя. По умолчанию ''false''.
  * ''selective'' — если ''true'', сработает в двух случаях:
      - клавиатура будет отправлена только пользователям, указанным в тексте сообщения @маркером;
      - если при отправке сообщения будет указано поле ''reply'', клавиатура отобразится только у пользователя с ''id'' равным ''reply''.
<code javascript>
bot.on(['/start', '/back'], msg => {
  
  var keyboard = bot.keyboard([
    ['/buttons', '/inlineKeyboard'],
    ['/start','/hide']
  ], { resize: true });
  
  return bot.sendMessage(msg.from.id, 'Keyboard example.', { markup: keyboard });

});
</code>
{{ :js:telegram:keyboard.jpg?nolink |}}

func:: Telegram.button(<location | contact>, <text>)
Создаёт объект-кнопку типа ''location '' или ''contact''. Нажатие кнопки ''location '' передаст координаты пользователя боту. Нажатие кнопки ''contact'' передаст номер телефона пользователя.
<code javascript>
bot.on('text', msg => {

  let markup = bot.keyboard([
    [bot.button('contact', 'Your contact'), bot.button('location', 'Your location')]
  ], { resize: true });

  return bot.sendMessage(msg.from.id, 'Button example.', { markup });

});

bot.on(['location', 'contact'], (msg, self) => {
  return bot.sendMessage(msg.from.id, `Thank you for ${ self.type }.`);
});
</code>

func:: Telegram.inlineButton(<text>, {url | callback | inline})
Создаёт объект-кнопку ''InlineKeyboardButton''.
func:: Telegram.inlineKeyboard([array of arrays])
Создаёт объект встроенную клавиатуру.

{{ :js:telegram:inline_keyboard.jpg?nolink |}}

<code javascript>
  var keyboard = bot.inlineKeyboard([
    [
      bot.inlineButton('callback', { callback: 'this_is_data' }),
      bot.inlineButton('inline', { inline: 'some query' })
    ], [
      bot.inlineButton('url', { url: 'https://telegram.org' })
    ]
  ]);

  return bot.sendMessage(msg.from.id, 'Inline keyboard example.', { markup: keyboard });
</code>

===Стандартные методы Telegram:===

Библиотека использует стандартные для Telegram API имена методов.


func:: Telegram.sendMessage(chat_id, text, {reply, markup, notify})
Функция отправляет сообщение с текстом ''text'' пользователю ''chat_id''. Третьим параметром может передаваться объект с полями:
  * ''notify'' — если установлен в ''false'', пользователи iOS не получат уведомление о сообщении, а пользователи Android получат уведомление без звука.
  * ''reply'' — ''id'' сообщения, на которое отправляется ответ. 
  * ''markup'' — JSON-сериализованный объект с объектом-клавиатурой.

func:: Telegram.answerCallback(callback_query_id, text | undefined, show_alert)
Функция отправляет ответ на запрос пользователя, произведённый со "встроенной" клавиатуры.
  * ''callback_query_id'' — уникальный идентификатор запроса, на который отправляется ответ.
  * ''text'' — текст уведомления. 0-200 символов.
  * ''show_alert'' — показывать уведомления или нет. По умолчанию ''false''.

func:: Telegram.sendLocation(chat_id, [latitude, longitude], {reply, markup, notify})
Функция отправляет сообщение пользователю ''chat_id'' с координатами ''latitude'' (широта) и ''longitude'' (долгота).
<code javascript>
// обменяться координатами с ботом
bot.on('location', (msg, self) => {
  return bot.sendLocation(msg.from.id, [55.743853, 37.656175]);
});
</code>


==== События ====

Используйте ''bot.on(<event>, <function>)'' для обработки событий в процессе работы.

События:
  * ''/*'' — любая команда
  * ''/<cmd>'' — определённая команда
  * ''connect'' — бот подключился к Telegram
  * ''disconnect'' — бот отключился
  * ''update'' — обновление
  * ''callbackQuery'' — пришёл ответ от встроенной кнопки

События для сообщений:
  * ''contact'' – данные пользователя
  * ''location'' – данные местоположения
  * ''text'' — текстовое сообщение
  * ''*'' — любой тип сообщений

Для обработки команды с параметрами просто добавьте слеш ''/'':
<code javascript>
bot.on('/hello', msg => {
  var params = msg.text.split(' ');
  return bot.sendMessage(msg.from.id, 'Hello, '+params[1]+' '+params[2]+'!');
});
</code>


Интерфейс библиотеки основан на библиотеке [[https://github.com/kosmodrey/telebot/|telebot]].

Подробное описание [[https://core.telegram.org/bots/api|API Telegram]].