Запросы к API

Основная информация о запросах

Запрос — обращение от одного сервиса к другому сервису для получения или отправки информации.

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

Отправка методом GET →
Отправка методом POST →
Удаление последнего сообщения от бота с помощью POST-запроса →
Удаление последнего сообщения от пользователя с помощью POST-запроса →
Удаление любого сообщения от бота с помощью POST-запроса →
Отправка стикера с помощью POST-запроса →
Отправка запроса в GPT с помощью POST-запроса →
Обработка ответа — объект →

Ботмама умеет отправлять запросы и принимать ответы только в формате JSON. Если нужная вам система не поддерживает JSON, нужно искать сервис, который изменяет формат запроса, или писать кодом скрипт обработки на сервере. Ещё можно использовать сервисы, которые заменяют интеграцию запросами — например, Zapier.

Объем массива с объектами для отправления запросом может быть не более 1 Мб

Существует множество типов запросов, мы используем только самые распространённые: GET, POST, PUT, PATCH, DELETE.

GET чаще всего используется как запрос получения информации. В отдельных случаях он может использоваться равнозначно с другими типами. Например, в Telegram можно использовать и GET, и POST для одинаковых запросов.
POST используется для отправки информации и создания объектов. Этим методом чаще всего создаются заявки, формируются заказы и т.д.
PUT обновляет информацию об объекте.
PATCH частично обновляет информацию об объекте.
DELETE удаляет созданный объект.

Тело в GET запросе можно передавать в строке URL, для остальных запросов — только в специальном поле компонента.

Основная информация об ответах

Ответом на запрос может быть информация об ошибке или об удачном запросе с дополнительными данными или без них.

Об ответах на запросы можно подробно узнать в Википедии

Чаще всего приходят ответы успеха и ошибок.

Ответы ожидаются в течении одной минуты, затем приходит ошибка по таймауту. Изменить время ожидания можно через поддержку

Если запрос прошёл успешно, код будет иметь значение, начинающееся на 2:

200 OK — успешный запрос.
201 Created — в результате успешного выполнения запроса был создан новый ресурс.
202 Accepted — запрос был принят на обработку, но она не завершена.

Если запрос не прошёл из-за ошибки параметров запроса, Ботмама считает его успешным. Такие ошибки начинаются на 4:

400 Bad Request — сервер обнаружил в запросе клиента синтаксическую ошибку. Этот код используется для любых ошибок такого типа, если разработчик сервиса не вложил другие значения.
401 Unauthorized — для доступа к запрашиваемому ресурсу требуется авторизация.
403 Forbidden — сервер понял запрос, но он отказывается его выполнять из-за ограничений в доступе для клиента к указанному ресурсу.
404 Not Found — запрашиваемый ресурс не был найдет или не существует.

Если запрос не прошёл из-за ошибки сервера (запрос упал по таймауту, сервер недоступен или тело не удалось распарсить), бот исполняет экран ошибки. В остальных случаях сработает экран успеха. Если ответ пришел валидным со статусом не 200, нужно установить компонент Развилка после запроса и смотреть на статус в теле. Исходя из этого направлять на нужный экран. Ошибки сервера начинаются на 5:

500 Internal Server Error — любая внутренняя ошибка сервера. Этот код используется, если разработчик не добавил код для описания данной ошибки.
501 Not Implemented — сервер не может обработать запрос. Например, вы используете несуществующий метод.
502 Bad Gateway — когда сервер, к которому вы делаете запрос, фактически является буфером между вами и другим сервером, получает некорректный ответ от другого сервера.
503 Service Unavailable — сервер временно не может обрабатывать запросы. Такие ошибки возникают, когда сервер выключен, не имеет доступа к Сети или ограничен в доступе.
504 Gateway Timeout — когда сервер, к которому вы делаете запрос, фактически является буфером между вами и другим сервером, не получает ответ от другого сервера.

Отправка методом GET

Создание URL для GET-запроса

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

1. Добавим токен бота в URL-запрос.

Все запросы в Telegram создаются по шаблону:

https://api.telegram.org/bot<token>/НАЗВАНИЕ_МЕТОДА

Каждому боту при создании присваивается уникальный токен вида 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11.

Авторизация запросов к Telegram проходит по токену бота. Это значит, что срабатывать запрос будет в боте, токен которого вы указали. К примеру, отправляя запрос с текстом, вы можете указать токен другого бота, и тогда сообщение будет приходить в него.

Пока что URL будет таким:

 https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/НАЗВАНИЕ_МЕТОДА

Где вместо 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 — токен вашего бота.

2. Добавим метод API.

Метод API — действие, которое должна совершить система в заданном боте.

Один из самых простых методов — sendMessage. Он отправляет текст.

После вставки метода API наш шаблон выглядит так:

https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/sendMessage

3. Добавим параметры запроса.

Параметры запроса — обязательные и дополнительные данные, которые конкретизируют, какое действие произойдёт. Например, параметры получателя или текст, который ему придет.

Обязательными параметрами являются chat_id и text:

chat_id — уникальный идентификатор пользователя в Telegram. Его мы получаем из переменной {{this_user.platform_id}}. Чтобы отправить сообщение определённому пользователю, нужно вставить значение его переменной. В нашем примере мы выводим значение из переменных пользователя.
text — текст сообщения, которое мы отправляем.

Для передачи пробелов в URL запроса нужно заменять их знаком +. Если отправить текст без замены, он оборвётся на первом пробеле.

Для запроса методом GET метод API и параметры передаются в URL запроса. Параметры от метода API отделяются знаком вопроса. Значение параметра отправляется после знака равенства. Между собой параметры отделяются знаком &.

4. Формируем шаблон GET-запроса.

https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/sendMessage?параметр1=значение1&параметр2=значение2

Вместо параметра1 добавим chat_id, значение1 выведем из переменных {{this_user.platform_id}}.

При необходимости, в значении1 можно указать конкретное значение.

Вместо параметра2 добавим text, в значение2 напишем текст, который должен прийти в бота.

URL GET-запроса готов:

https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/sendMessage?chat_id={{this_user.platform_id}}&text=Привет+из+бота!

Настройка компонента

1. Добавьте компонент Запрос на экран.

2. Выберите Метод запроса — GET.

3. Укажите URL запроса.

4. Укажите Экран, который исполнится при удачном выполнении запроса.

5. Укажите Экран, который выполнится при ошибке запроса.

6. Если требует API, добавьте дополнительные заголовки запроса в выпадающем меню компонента. Не удаляйте заголовки по умолчанию.

7. Задайте Имя переменной для тела ответа, если нужно записать ответ от сервера не в last_request, куда ответ приходит по умолчанию.

8. Задайте Имя переменной для кода ответа, если нужно записать ответ от сервера не в last_request_status_code, куда ответ приходит по умолчанию.

9. Задайте Имя переменной для заголовков ответа, если предполагается, что в заголовках придут важные данные. Например: токены авторизации, куки, подпись HMAC или еще что-то, что может потребоваться дальше для использования в боте.

10. Разверните настройки компонента для продолжения.

11. Отметьте галочками, какие статусы ответов будут считаться успешными, а какие — нет.

12. Для использования данных для авторизации по http basic authentication отметьте галочкой Использовать HTTP-авторизацию.

13. Отметьте галочкой Кодировать тело запроса, если нужно передать параметры по стандарту Юникод.

14. Отметьте галочкой Пропустить проверку HTTPS-сертификата, если у вас возникли проблемы с валидностью сертификата. Бот продолжит работу, но мы рекомендуем исправлять проблемы с сертификатом как можно быстрее.

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

Отправка методом POST

Создание URL для POST-запроса

Так как в POST запросе, параметры запроса и их значения составляют тело запроса, то в строке URL остаются только:

https://api.telegram.org/bot<token>/НАЗВАНИЕ_МЕТОДА

Где <token> — токен бота, где будет срабатывать запрос.</token>

Пример токена: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11.

Название метода оставим, как в прошлом примере — sendMessage.

Получаем URL такого вида:

https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/sendMessage

Параметры в URL, как в GET запросе, добавлять не нужно.

Для метода POST, в URL передаётся только метод API, параметры отправляются в теле запроса в формате JSON.

JSON — один из форматов данных. Он состоит из пар данных: ключ-значение. Ключ — название параметра, значение — значение параметра (может быть определенным или переменной).

Чтобы сделать тело с нашими параметрами, указываем их в формате JSON:

{
"chat_id": "{{this_user.platform_id}}",
"text": "Привет из бота!"
}

Важно следить за синтаксисом. Если вы забудете поставить хотя бы один символ, запрос не сработает. Это самая распространённая ошибка при отправке запросов.

Переносить строки можно с помощью \n, но такие символы ломают JSON. Чтобы JSON не ломался, нужно экранировать таким образом: /\n. Но так сделать не получится, если мы отправляем в переменной var текст от пользователя. В таком случае, нужно использовать хелпер escapeJsonEntities таким образом: {{escapeJsonEntities var}}.

Настройка компонента

1. Добавьте компонент Запрос на экран.

2. Выберите Метод запроса — POST.

3. Укажите URL запроса.

4. Укажите Экран, который исполнится при удачном выполнении запроса.

5. Укажите Экран, который выполнится при ошибке запроса.

6. Тело запроса для метода POST указывается, если того требует API. Поддерживается только в формате JSON.

7. Если требует API, добавьте дополнительные заголовки запроса в выпадающем меню компонента. Не удаляйте заголовки по умолчанию.

8. Задайте Имя переменной для тела ответа, если нужно записать ответ от сервера не в last_request, куда ответ приходит по умолчанию.

9. Задайте Имя переменной для кода ответа, если нужно записать ответ от сервера не в last_request_status_code, куда ответ приходит по умолчанию.

10. Задайте Имя переменной для заголовков ответа, если предполагается, что в заголовках придут важные данные. Например: токены авторизации, куки, подпись HMAC или еще что-то, что может потребоваться дальше для использования в боте.

11. Разверните настройки компонента для продолжения.

12. Отметьте галочками, какие статусы ответов будут считаться успешными, а какие — нет.

13. Для использования данных для авторизации по http basic authentication отметьте галочкой Использовать HTTP-авторизацию.

14. Отметьте галочкой Кодировать тело запроса, если нужно передать параметры по стандарту Юникод.

15. Отметьте галочкой Пропустить проверку HTTPS-сертификата, если у вас возникли проблемы с валидностью сертификата. Бот продолжит работу, но мы рекомендуем исправлять проблемы с сертификатом как можно быстрее.

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

Удаление последнего сообщения от бота с помощью POST-запроса

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

Удаление последнего сообщения с помощью Нативного запроса →

Для тестирования метода POST можно попробовать удалить предыдущее сообщение методом deleteMessage.

Все шаги по созданию запроса на удаление последнего сообщения от чат-бота вы можете посмотреть в видеоуроке:

Обязательные параметры:

chat_id — уникальный идентификатор пользователя в боте. Его мы получаем как основную переменную {{this_user.platform_id}}.
message_id — уникальный идентификатор сообщения, находится в переменной {{lastMessageId}}.

Создадим POST-запрос deleteMessage в конструкторе:

1. Добавьте компонент Запрос на экран.

2. Выберите Метод запроса — POST.

3. Укажите URL запроса.

Путь запроса (URL) будет иметь такой вид:

https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/deleteMessage

Где где 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 — токен вашего бота.

4. Укажите Экран, который исполнится при удачном выполнении запроса.

5. Укажите Экран, который выполнится при ошибке запроса.

6. Добавьте Тело запроса. Поддерживается тело только в формате JSON.

{
"chat_id": "{{this_user.platform_id}}",
"message_id": "{{lastMessageId}}"
}

11. Разверните настройки компонента для продолжения.

12. Отметьте галочками, какие статусы ответов будут считаться успешными, а какие — нет.

14. Отметьте галочкой Кодировать тело запроса, если нужно передать параметры по стандарту Юникод.

Теперь последнее сообщение будет удаляться из диалога с ботом в мессенджере, если запрос такой запрос установить в конструкторе сразу за сообщением.

Подобным образом можно удалить последнее сообщение от пользователя.

Все шаги по созданию запроса на удаление последнего сообщения от пользователя вы можете посмотреть в видеоуроке:

Все параметры будут такими же, как и в удалении последнего сообщения от бота, кроме Тела запроса.

Тело запроса будет таким:

{
"chat_id": "{{lastUpdate.update.chat.id}}",
"message_id": "{{lastUpdate.update.message_id}}"
}

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

Это может быть Развилка, Ввод от пользователя или на экран с запросом должна вести Перемотка с активным чекбоксом «‎Остановить бота после перемотки до следующего сообщения от пользователя».

Удаление любого сообщения от бота с помощью POST-запроса

Все шаги по созданию запроса на удаление любого сообщения от бота вы можете посмотреть в видеоуроке:

Методом deleteMessage также можно удалить любое сообщение от бота.

Для этого перезапишите {{lastMessageId}} удаляемого компонента в другую переменную с помощью компонента Запись переменной.

В поле Имя задайте новое имя переменной, в поле Значение впишите {{lastMessageId}}.

В нашем примере новое имя для переменной с сообщением — dlt.

В будущем добавим её в тело запроса на удаление в двойных фигурных скобках: {{dlt}}.

Для наглядного примера удаления любого сообщение от бота, а не только последнего, как в прошлом примере, экран с запросом добавим после всех сообщений.

После записи ID экрана в переменную, оформим запрос на удаление этого экрана.

Обязательные параметры:

chat_id — уникальный идентификатор пользователя в боте. Его мы получаем как основную переменную {{this_user.platform_id}}.
message_id — уникальный идентификатор сообщения, находится в переменной {{lastMessageId}}.

Создадим POST-запрос deleteMessage в конструкторе:

1. Добавьте компонент Запрос на экран.

2. Выберите Метод запроса — POST.

3. Укажите URL запроса.

Путь запроса (URL) будет иметь такой вид:

https://api.telegram.org/bot12345/deleteMessage

Где где 12345 — токен вашего бота.

4. Укажите Экран, который исполнится при удачном выполнении запроса.

5. Укажите Экран, который выполнится при ошибке запроса.

6. Добавьте Тело запроса. Поддерживается тело только в формате JSON.

Не забудем добавить нашу перезаписанную переменную в message_id.

    {
    "chat_id": "{{this_user.platform_id}}",
    "message_id": "{{dlt}}"
    }

8. Задайте Имя переменной для тела ответа, если нужно записать ответ от сервера не в last_request, куда ответ приходит по умолчанию.

9. Задайте Имя переменной для кода ответа, если нужно записать ответ от сервера не в last_request_status_code, куда ответ приходит по умолчанию.

11. Разверните настройки компонента для продолжения.

12. Отметьте галочками, какие статусы ответов будут считаться успешными, а какие — нет.

14. Отметьте галочкой Кодировать тело запроса, если нужно передать параметры по стандарту Юникод.

Если все сделано правильно, то удаляться будет то сообщение, message_id которого мы перезаписали и затем добавили в Тело запроса.

Отправка стикера с помощью POST-запроса

Все шаги по созданию запроса для отправки стикера от бота вы можете посмотреть в видеоуроке:

Отправим в чат стикер методом sendSticker.

Стикер можно отправлять как обычным Запросом к API, так и Нативным запросом.

Обязательные параметры:

chat_id — уникальный идентификатор пользователя в боте. Его мы получаем как основную переменную {{this_user.platform_id}}.
sticker — уникальный идентификатор стикера. ID стикера можно узнать, прислав стикер боту Sticker ID.

Создадим POST-запрос sendSticker в конструкторе:

1. Добавьте компонент Запрос на экран.

2. Выберите Метод запроса — POST.

3. Укажите URL запроса.

Путь запроса (URL) будет иметь такой вид:

https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/sendSticker

Где 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 — токен вашего бота.

4. Укажите Экран, который исполнится при удачном выполнении запроса.

5. Укажите Экран, который выполнится при ошибке запроса.

6. Добавьте Тело запроса. Поддерживается тело только в формате JSON.

{
"chat_id": "{{this_user.platform_id}}",
"sticker": "12345"
}

Где 12345 — ID отправляемого стикера.

11. Разверните настройки компонента для продолжения.

12. Отметьте галочками, какие статусы ответов будут считаться успешными, а какие — нет.

14. Отметьте галочкой Кодировать тело запроса, если нужно передать параметры по стандарту Юникод.

Если все сделано верно, то при исполнении Запроса, в бот придет стикер.

Отправка запроса в GPT с помощью POST-запроса

Обратимся к GPT с помощью POST запроса. Ответ от нейросети выведем в боте.

Обязательные параметры:

model — языковая модель, на котором нам ответит GPT, рекомендуем использовать text-davinci-003
prompt — текст, который отправиться в GPT. Текст можно заранее записать в переменную и вывести в теле запроса
max_tokens — максимальное количество символов в ответе от gpt. Значение может быть от 16 до 4000

Создадим POST-запрос к GPT в конструкторе:

1. Добавьте компонент Запрос на экран.

2. Выберите Метод запроса — POST.

3. Укажите URL запроса.

Путь запроса (URL) будет иметь такой вид:

https://api.openai.com/v1/completions

4. Укажите Экран, который исполнится при удачном выполнении запроса.

5. Укажите Экран, который выполнится при ошибке запроса.

6. Добавьте Тело запроса. Поддерживается тело только в формате JSON:

    {
      "model": "text-davinci-003",
      "prompt": "{{prompt}}",
      "max_tokens": 400
    }

7. Добавьте дополнительный заголовок запроса:

Ключ: Authorization
Значение: Bearer 12345xQWERTY, где 12345xQWERTY — ваш токен, который вы получили в OPEN AI.

Если доступ из вашей страны заблокирован, воспользуйтесь VPN.

Получить токен можно в личном кабинете Open AI (LogIn — API). В разделе Overview откройте вкладку Personal и выберите в ней раздел View API keys.

Сгенерируйте токен с помощью кнопки Create new secret key.

Не удаляйте заголовки по умолчанию.

8. Задайте Имя переменной для тела ответа, если нужно записать ответ от сервера не в last_request, куда ответ приходит по умолчанию.

9. Чтобы ответ от GPT, приходил сразу в бот, добавьте сообщение, где будет выводиться переменная с ответом. Если вы не меняли переменную для ответа по умолчанию, добавьте такой шаблон:

{{last_request.choices.[0].text}}

10. После ответа, можно добавить Перемотку на тот же самый экран, чтобы бы не перезапускать сценарий для нового обращения к GPT.

Обработка ответа — объект

Для примера мы будем использовать ресурс https://www.cbr-xml-daily.ru.

В нём мы выбираем запрос в формате JSON:

https://www.cbr-xml-daily.ru/daily_json.js

Открываем его как обычную ссылку в браузере и получаем ответ в JSON-формате.

Чтобы ответ был удобным для чтения, поставьте расширение на браузер. Для Google Chrome это JSON Formatter.

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

Ответ на запрос находится в объекте {{last_request}}.

Чтобы вывести переменную внутри текста, вводим её внутри фигурных скобок. Для этого делаем запрос и выводим полученный ответ в тексте.

В начало ↑

Категории

Запросы к API

Основная информация о запросах

Основная информация об ответах

Отправка методом GET

Создание URL для GET-запроса

Настройка компонента

Отправка методом POST

Создание URL для POST-запроса

Настройка компонента

Удаление последнего сообщения от бота с помощью POST-запроса

Подобным образом можно удалить последнее сообщение от пользователя.

Удаление любого сообщения от бота с помощью POST-запроса

Отправка стикера с помощью POST-запроса

Отправка запроса в GPT с помощью POST-запроса

Обработка ответа — объект

Была ли статья полезна?

Спасибо за отзыв!

Посоветуйте, как нам улучшить статью

Спасибо за отзыв!