Telegram API и его использование. Telegram api что это Необходимые знания для работы с Telegram API

Tutorial

Чат боты - довольно интересная тема, которой интересуются как гики-энтузиасты, так и компании, которые хотят организовать взаимодействие со своими клиентами наиболее удобным для них способом

Сегодня я опишу вам простой пример создания бота Telegram с использованием платформы для создания разговорных интерфейсов API.AI, который будет приветствовать пользователя и отвечать на вопросы о погоде. По большей части я следовал этим инструкциям , в реальной практике, можно не ограничиваться погодой и реализовать интерфейсы
для автоматизированной поддержки или продаж.

Шаг первый: Подготовка инфраструктуры.

В этом кейсе мы будем использовать только Telegram бота и API.AI, оба сервиса предоставляются бесплатно - нам остается только завести учетные записи.

Создайте бота Telegram

Чтобы создать бота - просто напишите @BotFather (это такой бот, которые умеет создавать и настраивать другие боты):

Отправьте команду /newbot - так мы сообщаем @BotFather, что нам нужен новый бот
Теперь @BotFather попросит нас дать имя новому боту. Это имя будут видеть наши
будущие пользователи, поэтому название нужно давать понятное и простое.
Последним шагом укажем для бота username, в конце которого нужно обязательно
написать “bot”.
Если имя не занято, получаем сообщение с подтверждением и токен доступа.

Чтобы было понятнее - ниже скриншот со всеми действиям:

Немного теории

Пришло время создать агента API.AI, который в сущности является проектом или контейнером (как вам удобнее называть). Агент содержит настройки контекстов, сущностей и ответов:

“контекст” (Intent) отражает связь между тем, что сказал пользователь и
тем что должна сделать наша программа
“сущности” (Entities) - это инструмент извлечения значений параметров для
нашей программы из естественного языка (того что сказал или написал
пользователь)
“ответы ” - это конечный результат работы нашей программы, который мы
отправляем пользователю на его сообщение

Иногда для ответа пользователю достаточно информации из текущего диалога, в таком случае можно можно настроить статичные ответы в контекстах . В реальности для получения конкретного ответа нам может потребоваться внешний сервис или своя бизнес логика, например, чтобы получить информацию о погоде на завтра, нужно вызвать внешний API соответствующего сервиса. Позже я расскажу вам получать информацию из внешних систем, но для начала подготовим базу.

Создайте проект в API.AI

Для регистрации в API.AI вам потребуется аккаунт Google (достаточно завести в почту в Gmail). Теперь перейдите по адресу https://api.ai/ , нажмите на кнопку “SIGN UP FOR FREE”, а за тем выберите аккаунт, от имени которого хотите авторизоваться.

Теперь переходим к созданию самого агента. Нажмите на “Create agent” и укажите как минимум Имя(Name), Язык(Language) и Часовой пояс (Time Zone).

Шаг второй: Настройте агента.

Контекст отражает связь между тем, что говорит пользователь, и что должен сделать наш агент. В нашем случае, рассмотрим случай с прогнозом погоды:

Кликните на в разделе “Контекст” (Intents). В агенте уже настроены “контексты” на приветствие и ошибки, оставим их пока без изменений.
Укажите название для “контекста” - любое, главное чтобы оно было понятно вам и вашим коллегам.
В разделе “Реплики пользователя” (User Says) приведите примеры вопросов, который может ваш пользователь. Так как мы говорим о погоде, человек может задать вопрос в привязке ко времени и место - учтем это. Чем больше примеров вы предоставите в настройках, тем точнее будет работать агент. Некоторые примеры я привел на скриншоте:

В последнем примере слова “завтра” и “Нижнем Тагиле” подсвечены разными цветами - таким образом слова связываются с сущностями (Entities ) (в нашем случае сущности системные). Используя эти параметры агент “поймет” в каком городе и для какой даты нужно узнавать погоду.

Добавьте еще парочку своих примеров и нажмите “Сохранить” (SAVE).

Тестируем!

Проверим работу агента на простых вопросах, например, “Погода в Перми в среду”:

Все это время в правой верхней части экрана маячила надпись “Try it now” - напишите в это поле или произнесите простой вопрос о погоде и нажмите “Ввод”.

Мы еще не настраивали автоматический ответ, но некоторые параметры агент уже научился определять! В разделе INTENT отражено, что по “мнению” агента пользователь интересуется погодой (настроенный нами “контекст”), в PARAMETER - дату и название города в соответствующих переменных.

Добавьте автоматические ответы

Сделаем нашего агента разговорчивей! Пока мы не научились получать информацию о погоде из внешних источников, добавим в качестве ответов простые фразы.

Перейдите в раздел “ Ответы” (Response) и введите простые ответы аналогично тому, как вы заполняли “Реплики пользователя”:

Как видите - в ответах можно использовать ссылки на выявленные сущности, начните набирать $ - и интерфейс предложит вам выбрать конкретную переменную.

При формировании ответа агент учитывает количество определенных сущностей и не использует ответы, данных для которых недостаточно. Например, на вопрос без указания города агент использует ответ из второй строки.

Сохраните настройки и протестируйте еще раз:

Теперь у нас есть еще и ответ!

Шаг третий: Добавьте внешний сервис.

Наш агент уже “понимает” в каких случая пользователь хочет узнать погоду, на какое число и в каком городе. Теперь осталось получить эти данные из подходящего сервиса и передать агенту. Для этого вам нужно написать парочку скриптов на JS и разместить их в облачном сервисе, в нашем случае - Google Cloud Project.

Создайте стартовый JS файл

Для начала, создайте и перейдите в директорию с именем вашего проекта:

Linux или Mac OS X:

mkdir ~/
cd ~/

mkdir %HOMEPATH%
cd %HOMEPATH%

Теперь создайте файл index.js со следующим содержанием:

Код index.js

/* * HTTP Cloud Function. * * @param {Object} req Cloud Function request context. * @param {Object} res Cloud Function response context. */ exports.itsm365Weather = function itsm365Weather (req, res) { response = "This is a sample response from your webhook!" //Default response from the webhook to show it"s working res.setHeader("Content-Type", "application/json"); //Requires application/json MIME type res.send(JSON.stringify({ "speech": response, "displayText": response //"speech" is the spoken version of the response, "displayText" is the visual version }));

Настройте Google Cloud Project

Выполните настройки “Before you
begin” с 1 по 5 пункты

Разверните функцию в облаке выполнив в консоли:

gcloud beta functions deploy itsm365Weather --stage-bucket --trigger-http

где, itsm365Weather - название функции, а - наименование хранилища
данных для проекта.

После завершения операции вы увидите результат с URL http триггера:

Включите Webhook в API.AI

Убедитесь, что находитесь в нужном агенте, а затем кликните “Fulfillment ” в левом скрывающемся меню.
Включите использование Webhook в правой верхней части экрана.
Введите URL, полученный на предыдущем этапе.
Сохраните изменения.

Подключите исполнение новой функции в настройках “контекста”

Перейдите в настройки “контекста” прогноза погоды
Разверните блок Fulfillment в нижней части страницы
Отметьте галочкой “Использовать Webhook”
Сохраните настройки и проверьте результат:

Настройте API для получения погоды

Для простоты, воспользуемся сервисом WWO (World Weather Online), в котором вам нужно получить ключ API (просто зарегистрируйтесь через Facebook или Github).

Обновите код стартового JS файла, не забыв ввести ключ API для получения информации о погоде:

Исходный код сервиса для получения прогноза погоды

// Copyright 2017, Google, Inc. // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. "use strict"; const http = require("http"); const host = "api.worldweatheronline.com"; const wwoApiKey = "98cfb8e40ecc47c4a2f205209172608"; exports.itsm365Weather = (req, res) => { // Get the city and date from the request let city = req.body.result.parameters["geo-city"]; // city is a required param // Get the date for the weather forecast (if present) let date = ""; if (req.body.result.parameters["date"]) { date = req.body.result.parameters["date"]; console.log("Date: " + date); } // Call the weather API callWeatherApi(city, date).then((output) => { // Return the results of the weather API to API.AI res.setHeader("Content-Type", "application/json"); res.send(JSON.stringify({ "speech": output, "displayText": output })); }).catch((error) => { // If there is an error let the user know res.setHeader("Content-Type", "application/json"); res.send(JSON.stringify({ "speech": error, "displayText": error })); }); }; function callWeatherApi (city, date) { return new Promise((resolve, reject) => { // Create the path for the HTTP request to get the weather let path = "/premium/v1/weather.ashx?format=json&num_of_days=1" + "&q=" + encodeURIComponent(city) + "&key=" + wwoApiKey + "&date=" + date + "&lang=ru"; console.log("API Request: " + host + path); // Make the HTTP request to get the weather http.get({host: host, path: path}, (res) => { let body = ""; // var to store the response chunks res.on("data", (d) => { body += d; }); // store each response chunk res.on("end", () => { // After all the data has been received parse the JSON for desired data let response = JSON.parse(body); let forecast = response["data"]["weather"]; let location = response["data"]["request"]; let conditions = response["data"]["current_condition"]; let currentConditions = conditions["lang_ru"]["value"]; // Create response let output = `На ${forecast["date"]} в ${location["query"]} ${currentConditions}, температура воздуха от ${forecast["mintempC"]}°C до ${forecast["maxtempC"]}°C.`; // Resolve the promise with the output text console.log(output); resolve(output); }); res.on("error", (error) => { reject(error); }); }); }); }

Заново разверните функцию в облачном проекте.

Шаг четвертый: настройка ветвей диалога

Взаимодействуя с пользователем мы не можем быть уверены в том, что он предоставит нам всю информацию, необходимую для подготовки ответа во внешнем сервисе сразу в самом первом сообщении. В нашем примере для получения прогноза сервису потребуется дата и город. Если дата не известна, мы можем с успехом предположить, что пользователь подразумевает “сегодня”, но о городе мы можем узнать только от самого пользователя.

Сделайте “расположение” обязательным параметром

Откройте настройки контекста “Прогноз погоды” и укажите параметр geo-city обязательным к заполнению. Затем настройте уточняющий вопрос по ссылке в колонке “Prompts”.

Сохраните настройки и проверьте поведение агента, задав ему простой вопрос “погода”:

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

Создайте возвращаемое уточнение для расположения

Чтобы использовать данные полученные на предыдущих этапа взаимодействия с пользователем, вам потребуется настроить соответствующие уточнения.

В настройка контекста “прогноз погоды” вбейте в поле “Add output context” название возвращаемого уточнения “location” и сохраните настройки.

Создайте новый контекст для уточнения

Удобно, когда по одному и тому же расположению можно задавать несколько вопросов, при этом не уточнять у пользователя, какой город он имеет ввиду. Вы уже настроили возвращаемое уточнение, которе как можно использовать для обработки уточняющих вопросов.

Создайте новый контекст в разделе Intents или кликните по значку в строке
Intents левого выдвигающегося меню.
Назовите новый контекст “Уточнение погоды” (или любое другое понятное вам название).
Установите входящие и исходящие уточнения как “location”
Добавьте реплики пользователя, например, “Что на счет завтра”
Добавьте параметр сущности со следующими значениями:
- Parameter Name:
geo-city
- Value: #location.geo-city
Добавьте ответ для пользователя в раздел “Response ”:
- “Извини, но я не могу получить прогноз на $date-period в #location.geo-city”
Включите использование webhook в меню Fulfillment .
Сохраните настройки и протестируйте в консоли:

Шаг пятый: Приветствие и обработка непредвиденных ситуаций

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

Настройте ответы “по умолчанию” для непредвиденных ситуаций

Если пользовать задаст непредвиденный вопрос (в нашем случае - не о погоде) агент включит в работу контекст для обработки непредвиденных ситуаций (Default Fallback Intent ):

Перейдите в настройке этого контекста, при необходимости настройте свои варианты ответов.

Настройте контекст приветствия

Приветствие можно настроить аналогичным способом в соответствующем контенте -
Default Welcome Intent

Шаг шестой: запустите бота

Подключите Telegram бота к агенту

Перейдите в настройки “Интеграций” (Integrations) и включите бота в разделе
“One-click integrations”:

Скопируйте в поле “Telegram token” токен, который вы получили у @botFather и
нажмите на START.

Проверьте работу бота

Перейдите в своего бота и попробуйте ему что-нибудь написать, в моем случае это
@itsm365_weather_bot (я пользовался бесплатными аккаунтами погоды, поэтому после 500 запросов в день бот превратится в тыкву).

Заключение

API.AI уже вполне можно пользоваться для построения диалоговых интерфейсов в мессенджерах, чатах поддержки с соцсетях. С учетом того, что инструмент можно легко интегрировать со своими сервисами - это удобная рабочая лошадка для автоматизации коммуникации с вашими пользователями.

P.S. Этой мой первый пост, буду признателен за конструктивную обратную связь!

Теги: Добавить метки

Приложение Телеграмм честно может похвастаться открытием новой, абсолютно уникальной базы для создания ботов. Хоть ботовая платформа была разработана еще в начале лета (презентация состоялась 24.06), лишь малая часть активных внешних разработчиков начала усиленно шлифовать и разрабатывать собственные приложения. Сегодня бот — незаменимый помощник для Telegram , ведь с его помощью устанавливается связь с запрашиваемыми серверами TelegramBot API . Кроме этого, сам процесс работы бота направлен на обращения на URL с заданными параметрами, после которого Телеграмм выдает JSON — ответ. Давайте же окунемся вглубь вопроса и рассмотрим пример создания бота (тривиального типа).

Процедура регистрации приложения (бота)

Перед тем, как начать непосредственную разработку и заливку бота в общий интерфейс и чат, необходимо присвоить вашей мини — программе индивидуальный код (типа id ), который является уникальным персонифицирующим токеном. Для того, чтобы осуществить данную операцию, необходимо отправить запрос в специфический бот — @BotFather .

Для того, чтобы осуществить данную операцию, необходимо следовать такому алгоритму действий:

пишем текстовое сообщение с информационным наполнением «start »;
после этого, получаем перечень всех возможных опционных команд и функций;
далее отправляем боту сообщение с текстовым наполнением «newbot » и по входящему запросу существующего бота, придумываем никнейм своему боту (единственное условие: в имени должен быть суффикс/префикс «bot »);
если все условия и правила учтены, то существующий бот выдает вам запрос и разрешительную ссылку (быстрое добавление созданного бота в список имеющихся контактов).

В принципе, к этому моменту уже можно запускать бот или же, при желании, возможно создать приветственное сообщение для будущих пользователей и описание бота. Возможно, если вы хотите поразить определенную целевую аудиторию, то может добавить созвучную музыкальную композицию или изображение. Важный совет: стоит проверить уникальность и пригодность вашего токена, перейдя по адресной ссылке (api.telegram.org/bot/getMe) . Процесс программирования ботов

Обычно боты создаются в режиме Python3 , но благодаря прогрессивности ИТ — технологий, можете воспользоваться любым удобным и привычным режимом. Телеграмм настроен на автоматическую загрузку сообщений, поэтому уместно создать конфиденциальное облако, которое значительно ускорить процесс выкачки текстовых сообщений (наиболее быстрым и применимым являетсяtornado.web. ). Пусть каркасная часть бота будет отражена в определённой фразе (логичнее использовать ту, которая отражает информационное наполнение запрограммированного бота). Тогда, перед тем, как запустить бот, необходимо провести процедуру активации WebHook с локализацией на собственный адрес. Далее настраиваем привычный сигнал (выход на 6) и отображаем нагружение происходящих событий/ действий.

словарный запас;
функциональная особенность отправки (пересылки) текстовых ответов;
формирование сообщений.

После того, как вы занесли все нюансы в логику бота, необходимо начать разработку основных команд, которыми будет обладать ваша программа.

Создание команд

По правилам программы Телеграмм, абсолютно каждый бот (в не зависимости от специфики, популярности и загруженности) должен реагировать на 2 команды:

Start ;
Help .

Первая команда создана для идентификации бота, а не для просмотра заложенной информации. Зачастую, ее использование тесно связано с процедурой авторизации каких — либо программ.

Команда «Help » направлена на отражение основных параметров бота, его специфических характеристик, особенностей и команд.

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

Всеобщность

Вы уже заметили, что программа Телеграмм присылает абсолютно целостные и значимые в смысловом плане сообщения, не разбивая их на отдельные нелепые части. Поэтому, возникает возможность запрограммировать ваш бота на озвучки человеческой речи (голосовое уведомление). Единственный нюанс в том, что «говорливый» бот будет доступен только в приватных сообщениях, ибо в чате данная особенность невозможна. Для того, чтобы запустить процесс «говорения» бота совершаем ряд связных операций:

отправляем текстовое сообщение «setprivacy» на адрес @BotFather;
переключаемся на приватность;
в перечне команд добавляем опцию «псевдо — речь».

После этого, бот может озвучивать сообщения и предавать информацию в голосовом режиме.

Медиа аспекты и возможности

Боты не многим отличаются от реальных пользователей месседжера Телеграмм, поэтому у них тоже есть возможность общаться с использованием картинок, музыкальных файлов, видеозаписей и стикеров.

Для того, чтобы заполучить пакет стикеров необходимо отправить текстовое сообщение «at_sticker » и провести модификацию к параметрам send_reply . Таким образом, помимо текста ваш бот будет высылать и забавные стикеры и отображать показатели времени.

Потенциал

С помощью надежной платформы API , боты могут стать незаменимыми помощниками и основой для автоматизации процессов, формировании викторин, опросов, конкурсов и отправки уведомительных сообщений. Основной упор можно сделать на специфику CTF, DozoR.

Рамки

Сегодня имеются жёсткие рамки в использование ВебХук . Дело в том, что он функционирует только на основе https (при наличии валидного сертификата). Далёко не каждый разработчик имеет валидный сертификат. А причина в том, что отсутствует поддержка от ДНС. Но, благодаря наличию ручного режима в Telegramm , есть возможность дифференцировать коды и службы имеющихся данных под те, к которым подстроена ваша программа, проводящие выкачку и пересылку сообщений на локальные адреса.

Другие материалы про ботов Telegram:

Робот Антон — роботы в Telegram
Возможности разработчиков api Telegram
Боты Telegram
Telegram 3.0 имеет функцию запуска полезных Ботов

Tutorial