Бот - это специализированный тип пользователя. Под ним нельзя залогиниться, а управлять может создатель через InfoBot-а. Бот подчиняется общим правам системы, т.е. должен быть добавлен в чат в который должен писать/читать. Боту передается текст сообщений обращенных к нему, если задан обратный url. Читать все сообщения чата бот не может.
Создание и управление ботом
Cоздавать и менять настройки бота можно с помощью бота InfoBot в своем Info Chat-е.
Для создания бота используется команда @infobot new_bot helpbot ChatHelpBot, где:
- первый аргумент, уникальное имя, которое должно оканчиваться на
bot, -
второй аргумент, читаемое имя.
В ответ придет сообщение с ключом АПИ, где:
URL_KEY, первые 8 символов используются при создании url бота-
API_KEY, отбросим первые 20 символом и получим ключ АПИ, для отправки постов и доступа к другим АПИ (через заголовокX-APIToken).
Команда боту
@infobot new_bot uniquenamebot VisibleNameBot
Ответ бота
New bot @uniquenamebot created
Secret key: as3afgmkkmmepfbosv6o6hpph8s3fj2b9kpd0jutpts3i9ct67u
To start using bot you need setup callback url with command set_bot uniquenamebot url http://example.com/as3afgmk
Url must contain as3afgmk
API - as3afgmkkmmepfbosv6o6hpph8s3fj2b9kpd0jutpts3i9ct67u, где
URL_KEY = as3afgmkAPI_KEY = 6hpph8s3fj2b9kpd0jutpts3i9ct67u
as3afgmk kmmepfbosv6o 6hpph8s3fj2b9kpd0jutpts3i9ct67u
|--------| | |
URL_KEY(8) | |
|---------(20)--------|------------API_KEY------------|
{
`X-APIToken`: '6hpph8s3fj2b9kpd0jutpts3i9ct67u'
}
Установка url, на который будут приходить обращения к боту
Команда @infobot set_bot helpbot url http://example.com/as3afgmk, где
helpbot- уникальное имя бота,url- редактируемая опция,http://example.com/as3afgmk- значение опции, адрес, куда будут отправляться сообщения.
Получение детальной информация по боту
Команда bot_info <unique_name> позволит узнать подробную инормацию о боте , где
<unique_name>- уникальное имя созданного бота
Команда боту
bot_info uniquenamebot
Ответ бота
@uniquenamebot
---
NAME: VisibleNameBot
RECEIVER URL:
http://example.com/as3afgmk
on this url you will receive messages from users
SENDING URL:
POST https://api.verbosity.io/bot/message
BODY {"key": "6hpph8s3fj2b9kpd0jutpts3i9ct67u", "text": "example text", "chat_id": <chat_id:int>}
with this url you will be able to send messages to chats where your bot has access
KEY: as3afgmkkmmepfbosv6o6hpph8s3fj2b9kpd0jutpts3i9ct67u
Просмотр доступных команд
Команды можно посмотреть, отправив @infobot help
Команда боту
@infobot help
Ответ бота
bots - list your bots
new_bot <unique_name> <friendly name> - create new bot
set_bot <unique_name> <option> <value> - set option to bot
bot_new_key <unique_name> - generate new key
bot_info <unique_name> - bot details
Отправка сообщений
Отправка сообщений в неприватный чат
POST /bot/message
Parameters
No parameters
Request body
{
"key": "6hpph8s3fj2b9kpd0jutpts3i9ct67u"
"chat_id": 37, // int
"reply_no": null, // int or null
"text": "@all test" // text, 10k symbols limit
}
Responses
200 OK
{
"post_no": 123
}
Пример запроса
response = httpx.post("https://api.verbosity.io/bot/message", json={
"key": "6hpph8s3fj2b9kpd0jutpts3i9ct67u",
"text": "example text",
"chat_id": 37,
# "reply_no": 8 #ответ на сообщение
}
)
Отправка сообщений в приватный чат
По user_id
POST /msg/post/private
Parameters
No parameters
Request body
{
"text": "some text",
"user_id": 12
}
Responses
200 OK
{
"chat_id": 23,
"post_no": 123
}
Пример запроса
headers = {
"X-APIToken": "6hpph8s3fj2b9kpd0jutpts3i9ct67u"
}
response = httpx.post("https://api.verbosity.io/msg/post/private", headers = headers, json={
"text": "example text",
"user_id": 12
# "reply_no": 8 #ответ на сообщение
}
)
По email
POST /msg/post/private
Parameters
No parameters
Request body
{
"text": "some text",
"user_email": "user@example.com"
}
Responses
200 OK
{
"chat_id": 23,
"post_no": 123
}
Пример запроса
headers = {
"X-APIToken": "6hpph8s3fj2b9kpd0jutpts3i9ct67u"
}
response = httpx.post("https://api.verbosity.io/msg/post/private", headers = headers, json={
"key": "6hpph8s3fj2b9kpd0jutpts3i9ct67u",
"text": "example text",
"user_email": "user@example.com"
# "reply_no": 8 #ответ на сообщение
}
)
По уникальному имени
POST /msg/post/private
Parameters
No parameters
Request body
{
"text": "hello world!",
"user_unique_name": "unique_name"
}
Responses
200 OK
{
"chat_id": 23,
"post_no": 123
}
Пример запроса
headers = {
"X-APIToken": "6hpph8s3fj2b9kpd0jutpts3i9ct67u"
}
response = httpx.post("https://api.verbosity.io/msg/post/private", headers = headers, json={
"key": "6hpph8s3fj2b9kpd0jutpts3i9ct67u",
"text": "example text",
"user_unique_name": "unique_name"
# "reply_no": 8 #ответ на сообщение
}
)
Отправка файлов в чат
Бот может отправляеть файлы в чат составным запросом с помощью multipart/form-data, использующийся для отправки HTML-форм
POST https://file.verbosity.io/new/upload
Parameters
No parameters
Request multipart/form-data
chat_id = 37 &
size = {file_size}
data = {file_data}
Responses
200 OK
{
"guid": "2031c0eb0ff045c69dbbd9f9624f307b"
}
Пример запроса
headers = {"X-APIToken": "6hpph8s3fj2b9kpd0jutpts3i9ct67u"}
payload = {"chat_id": 70737, "size": len((open("example.txt", "rb")).read())}
data = {"data": open("example.txt", "rb")}
response = httpx.post("https://file.verbosity.io/new/upload", headers=headers, data=payload, files=data)
Пример запроса curl
-H "X-APIToken: ..."
-X POST
-F "size=`wc -c < ./ansible.log`"
-F "chat_id=37"
-F "data=@./ansible.log"
https://file.verbosity.io/new/upload;
Обработка ошибок
Ошибки доступа
{
"code": "access_deny"
"message": "...some text..."
}
Ошибки валидации
Можно определить по флагу "tamtam_response_api": true
{
"tamtam_response_api": true,
"codes": {"<field_name>|non_field": "str_code"},
"field_errors": {"<field_name>|non_field": "str_message"}
"extra": {}, // optioanl
"error": "str_message"
}
Получение сообщений
На адрес установленный командой @infobot set_bot helpbot url http://example.com/as3afgmk
POST-ом отправляется сообщение в формате json
{
// кто обратился к боту
"user_id": 12, // int
"user_unique_name": "real_user", // str or null, unique_name по user_id
// где было обращение (пост, чат, команда)
"post_no": 11, // int
"chat_id": 21, // int
"organization_id": null, // null or int
// что было написано боту
"text": "some text", // str
"text_parsed": [{"type": "text", "value": "some text"}], // list[dict], распознанные блоки форматирования текста
// если сообщение содержит ответ на другой пост, тут будет номер и текст этого поста
"reply_no": 7, // optional, int
"reply_text": "some text", // optional, str
// если сообщение содержит файл, тут будет guid и имя файла
"file_guid": "5d9d966e0dcc4cb28a86acd79323cf2b", // optional, str (hex)
"file_name": "example.txt", // optional, str
// список прикрепленных файлов (файлы будут загружены до отправки поста, куда они прикрепленны, но при обработке следует учитывать, что файл с указанным guid может отсутствовать или быть недоступен)
"attachments": null, // optional, list[str] - список guid файлов
}
и заголовок X-Signature - подпись пакета, ее можно проверить так:
BKEY = to_bytes(int("<key>", 32))
def _make_signature(body: str):
return str(base64.b64encode(
hmac.new(BKEY, bytes(body, "utf8"), digestmod=hashlib.sha256).digest()
), "utf8")
if request.headers["x-signature"] != _make_signature(await request.text()):
print("Check failed")
Команды бота (bot actions)
В случаях когда бот имеет небольшое число команд или требуется выбор из нескольких вариантов - ввод команд в диалоговом режиме может быть слишком сложным и неочевидным для пользователя. Бот, помимо входящих сообщений может обрабатывать команды (actions), которые бот сам формирует динамически в своих сообщениях в виде ссылок специального формата (валидных url):
bot://{action}?title={title}[&{key}={value}]
- action: <str:
a-z_> - имя команды - title:
- текст, отображаемый пользователю в сообщении - key, value:
- любые пользовательские параметры - общая длинна строки не более 1024 символов, строки следует прогнать через url-quoting
В результате пользователь увидит ссылку (позже будут и другие варианты отрисовки), нажав на которую боту будет направлен запрос с подписанными данными:
POST https://{bot-server-url}/act
{
"user_id": <int>, // пользователь, который нажал на action-ссылку
"chat_id": <int>, // чат в котором вызвана команда
"post_no": <int>, // пост в котором ботом была отправлена команда
"organization_id": <int> | null // команда в которой находиться чат
"action": <str> // имя команды
"params": {<str>: <str>} // все параметры после ?
}
Следует учитывать:
- action-ссылки принимаются только от ботов (обычный пользователь не может их формировать)
- нажатие на action-ссылку не сопровождается постом или каким-либо другим образом для всех участников чата
- action-ссылки можно нажимать много раз, в групповых чатах их может прожать любой участник
titleиuiзарезервированные служебные параметры
Пример:
Текст сообщения от бота
Выберите доску для размещения карточек по-умолчанию:
bot://set_default_board?title=Team%20board&board_id=54623
bot://set_default_board?title=My%20board&board_id=324512
bot://set_default_board?title=Main%20board&board_id=83924
Запрос на сервер бота при нажатии на ссылку My board пользователем (user#132)
POST https://example.com/as3afgmk/act
{
"user_id": 132,
"chat_id": 11768,
"post_no": 45876,
"organization_id": null,
"action": "set_default_board",
"params": {
"title": "My%20board",
"board_id": "324512"
}
}
Основные АПИ
Пробная OpenApi3 спецификация (могут быть отступления в ответах, ValidationError мало описан). Можно открыть в https://editor.swagger.io/ и использовать в качестве документации.
Ниже представленны некоторые из API
Пользователи
Получение информации о пользователе по id
Зная id пользователя можно запросить общую информацию о нем
GET /core/user?ids=11,12,15.
Parameters
ids - id пользователей
Request body
No body
Responses
200 OK
{
"users": [
{
"id": 0,
"name": "string",
"unique_name": "string",
"info": "string",
"info_parsed": [
{}
],
"deleted": true,
"active": true,
"time_updated": "string",
"time_created": "string",
"is_bot": true,
"organizations": [
0
]
}
]
}
Пример запроса
ids = ","join([11, 12, 15])
url = "https://api.verbosity.io/core/user?ids={ids}"
headers = {
"X-APIToken": "6hpph8s3fj2b9kpd0jutpts3i9ct67u",
}
response = httpx.get(url, headers = headers)
Получение информации о пользователе по unique name
Зная unique name пользователя можно запросить общую информацию о нем
GET /core/user?unames=user0,user1,user2.
Parameters
unique name - уникальное имя пользователей
Request body
No body
Responses
200 OK
{
"users": [
{
"id": 0,
"name": "string",
"unique_name": "string",
"info": "string",
"info_parsed": [
{}
],
"deleted": true,
"active": true,
"time_updated": "string",
"time_created": "string",
"is_bot": true,
"organizations": [
0
]
}
]
}
Пример запроса
unames = ","join(['user0','user1','user2'])
'
url = "https://api.verbosity.io/core/user?unames={unames}"
headers = {
"X-APIToken": "6hpph8s3fj2b9kpd0jutpts3i9ct67u",
}
response = httpx.get(url, headers = headers)
Чаты
Получить данные всех доступных чатов можно в 2 приема
Получение id чатов (независимо от статуса видимости)
GET /core/chat/sync
Parameters
No parameters
Request body
No body
Responses
200 OK
{
"chats": [
0
]
}
Пример запроса
url = "https://api.verbosity.io/core/chat/sync"
headers = {
"X-APIToken": "6hpph8s3fj2b9kpd0jutpts3i9ct67u"
}
response = httpx.get(url, headers = headers)
Получение данных чатов по id
GET /core/chat?ids=11,12,15.
Parameters
ids - id чатов
Request body
No body
Responses
200 OK
{
"chats": [
{
"id": 0,
"title": "string",
"description": "string",
"organization_id": 0,
"posts_live_time": 0,
"two_step_required": true,
"history_mode": "string",
"org_visible": true,
"allow_api": true,
"read_only": true,
"posts_count": 0,
"pm": true,
"e2e": true,
"time_created": "string",
"time_updated": "string",
"time_edited": "string",
"author_id": 0,
"tnew": true,
"adm_flag": true,
"custom_title": "string",
"is_favorite": true,
"inviter_id": 0,
"tshow": true,
"user_time_edited": "string",
"history_start": 0,
"pinned": [
0
],
"member_ids": [
0
],
"admin_ids": [
0
],
"group_ids": [
0
],
"guests": [
0
],
"thread_users": [
0
],
"thread_admins": [
0
],
"thread_groups": [
0
],
"last_msg": "string",
"last_read_post_no": 0,
"last_msg_author_id": 0,
"last_msg_author": "string",
"last_msg_bot_name": "string",
"last_msg_text": "string"
}
]
}
Пример запроса
ids = ","join([11, 12, 15])
url = "https://api.verbosity.io/core/chat?ids={ids}"
headers = {
"X-APIToken": "6hpph8s3fj2b9kpd0jutpts3i9ct67u"
}
response = httpx.get(url, headers = headers)
Бот может создавать/редактировать/удалять чаты в соответствии со своими правами. Редактирование состава участников чата ботам не доступно.
Для работы с приватными чатами, есть отдельное АПИ POST /core/chat/pm/{user_id}, которое возвращает id приватного чата, существующего или вновь созданного.
Бот может входить/выходить в/из чатов, скрывать ненужные, добавлять/убирать из избранных, форкать.
Команды
Получить данные всех доступных команд, можно в 2 приема
Получение id команд
GET /core/org/sync
Parameters
No parameters
Request body
No body
Responses
200 OK
{
"ids": [
0
]
}
Пример запроса
url = "https://api.verbosity.io/core/org/sync"
headers = {
"X-APIToken": "6hpph8s3fj2b9kpd0jutpts3i9ct67u"
}
response = httpx.get(url, headers = headers)
Получение данных команд по id
GET /core/org?ids=11,12,15.
Parameters
ids - id команд
Request body
No body
Responses
200 OK
{
"orgs": [
{
"id": 0,
"slug": "string",
"title": "string",
"description": "string",
"description_parsed": [
{}
],
"email_domain": "string",
"time_created": "string",
"time_updated": "string",
"two_step_required": true,
"default_chat_id": 0,
"is_member": true,
"is_admin": true,
"state": "string",
"inviter_id": 0,
"guests": [
0
],
"users": [
0
],
"admins": [
0
],
"groups": [
0
]
}
]
}
Пример запроса
ids = ","join([11, 12, 15])
url = "https://api.verbosity.io/core/org?ids={ids}"
headers = {
"X-APIToken": "6hpph8s3fj2b9kpd0jutpts3i9ct67u"
}
response = httpx.get(url, headers = headers)
Так же бот может создавать/редактировать/удалять команды в соответствии со своими правами. Входить по приглашению и покидать команды.
Редактирование состава участников чата ботам не доступно.