Команды ботов (/-автодополнение)

GET /api/v3/teams/{team_uid}/botcommands/{chat_jid}

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

Пример ответа:

{
    "_time": "11 ms",
    "ok": true,
    "result": [
        {
            "args": [
                "название стикерпака"
            ],
            "key": "/стикерпак",
            "meta": {},
            "title": "загрузить стикеры из телеграма (у вас должно быть разрешение автора стикерпака)"
        },
        {
            "args": [
                "номер телефона"
            ],
            "key": "/добавить",
            "meta": {},
            "title": "добавить участника в команду"
        },
        {
            "args": [],
            "key": "/онлайн",
            "meta": {},
            "title": "кто онлайн (DEBUG)"
        },
        {
            "args": [],
            "key": "/чпок",
            "meta": {},
            "title": "личное сообщение от нового контакта (DEBUG)"
        },
        {
            "args": [],
            "key": "/чпок2",
            "meta": {},
            "title": "новый контакт (DEBUG)"
        },
        {
            "args": [
                "количество"
            ],
            "key": "/спам",
            "meta": {},
            "title": "много сообщений (DEBUG)"
        },
        {
            "args": [
                "количество"
            ],
            "key": "/спам3",
            "meta": {},
            "title": "много сообщений, но медленно, раз в 3 секунды (DEBUG)"
        },
        {
            "args": [],
            "key": "/ссылкотест",
            "meta": {},
            "title": "много сообщений (DEBUG)"
        },
        {
            "args": [],
            "key": "/неделя",
            "meta": {},
            "title": "задачи, сделанные за прошлую неделю (DEBUG)"
        },
        {
            "args": [],
            "key": "/пушвкл",
            "meta": {},
            "title": "активизировать ВСЕ выключенные устройства для пушей (DEBUG)"
        },
        {
            "args": [],
            "key": "/пушвыкл",
            "meta": {},
            "title": "эмулировать ошибку — отключить все устройства (DEBUG)"
        },
        {
            "args": [],
            "key": "/пуш",
            "meta": {},
            "title": "послать мне пуш (DEBUG)"
        },
        {
            "args": [],
            "key": "/пуш3",
            "meta": {},
            "title": "послать мне пуш в другие команды (DEBUG)"
        },
        {
            "args": [],
            "key": "/пуш2",
            "meta": {},
            "title": "послать мне НЕ-data-пуш на активное устройство (DEBUG)"
        },
        {
            "args": [],
            "key": "/ пуш4",
            "meta": {},
            "title": "послать мне voip-пуш (DEBUG)"
        },
        {
            "args": [],
            "key": "/прогресс",
            "meta": {},
            "title": "Сообщение для тестирования сообщений с type=\"progress\" (DEBUG)"
        },
        {
            "args": [],
            "key": "/клавотест",
            "meta": {},
            "title": "tada.teamBot печатает... (DEBUG)"
        },
        {
            "args": [],
            "key": "/камикадзе",
            "meta": {},
            "title": "сообщение, которое само удалится (DEBUG)"
        },
        {
            "args": [
                "заголовок задачи"
            ],
            "key": "/задача",
            "meta": {},
            "title": "поставить себе новую задачу"
        }
    ]
}

#-автодополнение

GET /api/v3/teams/{team_uid}/sharplinks/{chat_jid}

Список доступных #-упоминаний

Пример ответа:

{
    "_time": "744 ms",
    "ok": true,
    "result": [
        {
            "key": "#Абырвалг",
            "meta": {
                "jid": "g-3f7e2a85-49f5-4586-8229-d9c52813dcb2",
                "public": true
            },
            "title": "Абырвалг"
        },
        {
            "key": "#Абырвалг",
            "meta": {
                "jid": "g-9ed2594e-9ba9-46f7-bc59-e53ee861298c",
                "public": true
            },
            "title": "Абырвалг"
        },
        {
            "key": "#Абырвалг",
            "meta": {
                "jid": "g-f2d5eab1-73f0-48f2-b742-22099243dace",
                "public": true
            },
            "title": "Абырвалг"
        },
        {
            "key": "#Абырвалг",
            "meta": {
                "jid": "g-4cedcb6a-1449-441b-a0bd-4e9f65777f91",
                "public": true
            },
            "title": "Абырвалг"
        },
        {
            "key": "#Абырвалг",
            "meta": {
                "jid": "g-95aed724-2cdc-4f2c-b087-31adaa169c94",
                "public": true
            },
            "title": "Абырвалг"
        },
        {
            "key": "#Общий_чат",
            "meta": {
                "jid": "g-0983bf0f-a625-411f-a989-537140b748bc",
                "public": true
            },
            "title": "Общий чат"
        }
    ]
}

@-автодополнение

GET /api/v3/teams/{team_uid}/atlinks/{chat_jid}

Список доступных @-упоминаний

Пример ответа:

{
    "_time": "18 ms",
    "ok": true,
    "result": [
        {
            "key": "@tada.teamBot",
            "meta": {
                "jid": "d-a2d94e8e-74aa-4b0b-b55d-0b4fc1ce07f4"
            },
            "title": "tada.teamBot"
        }
    ]
}

Отправка простого текстового сообщения

POST /api/v3/teams/{team_uid}/messages/{chat_jid}

Отправка текстового сообщения, аудиосообщения или файла.

Параметры:

  • type — или ничего, или "audiomsg" для загрузки аудиосообщения
  • text — текст сообщения
  • message_id – уникальный id сообщения. Необязательное поле
  • nopreview — если это поле есть и в нём значение "true", то не будут создаваться превью для ссылок на внешние ресурсы.

Чтобы отправить файл, надо отправить файл в поле file. Важно! В теле запроса должен быть не json, а данные, переданные в multipart/form-data . Примерно так:

<form method="post" enctype="multipart/form-data">
    <input type="file" name="file">
</form>

ВНИМАНИЕ! Для отправки message_id вместе с файлом (например, чтобы отследить это сообщение), этот message_id надо посылать GETом.

Пример запроса:

{
    "message_id": "38a1e388-e26b-4844-a2f3-7e6c5e4528cb",
    "text": "Я яблоко зеленое, спелое, садовое."
}

Пример ответа:

{
    "_time": "124 ms",
    "ok": true,
    "result": {
        "chat": "g-3f7e2a85-49f5-4586-8229-d9c52813dcb2",
        "chat_type": "group",
        "content": {
            "text": "Я яблоко зеленое, спелое, садовое.",
            "type": "plain"
        },
        "created": "2019-09-27T01:00:59.030433Z",
        "editable_until": "2019-09-28T01:00:59.030433Z",
        "from": "d-0b1b2362-fb69-4dd6-8bfb-90c89517168d",
        "gentime": 1569546059030447528,
        "is_last": true,
        "message_id": "38a1e388-e26b-4844-a2f3-7e6c5e4528cb",
        "prev": "cc8e9c13-4d18-479a-8109-82b7047d4e86",
        "to": "g-3f7e2a85-49f5-4586-8229-d9c52813dcb2"
    }
}

Отправка файла

POST /api/v3/teams/{team_uid}/messages/{chat_jid}

Пример запроса:

file: тест.zip

Пример ответа:

{
    "_time": "345 ms",
    "ok": true,
    "result": {
        "chat": "g-3f7e2a85-49f5-4586-8229-d9c52813dcb2",
        "chat_type": "group",
        "content": {
            "mediaURL": "http://127.0.0.1:8000/u/ed6fa57775db46ca90d8c30c7bbe0e72/%D1%82%D0%B5%D1%81%D1%82.zip",
            "name": "тест.zip",
            "size": 47132,
            "text": "Видео: http://127.0.0.1:8000/u/ed6fa57775db46ca90d8c30c7bbe0e72/%D1%82%D0%B5%D1%81%D1%82.zip",
            "type": "file"
        },
        "created": "2019-09-27T01:00:59.416504Z",
        "editable_until": "2019-09-28T01:00:59.416504Z",
        "from": "d-0b1b2362-fb69-4dd6-8bfb-90c89517168d",
        "gentime": 1569546059416728748,
        "is_last": true,
        "links": [
            {
                "pattern": "http://127.0.0.1:8000/u/ed6fa57775db46ca90d8c30c7bbe0e72/%D1%82%D0%B5%D1%81%D1%82.zip",
                "text": "127.0.0.1:8000/u/ed6fa57775db46ca90d8c30c7bbe0e72/%D1%82%D0%B...",
                "url": "http://127.0.0.1:8000/u/ed6fa57775db46ca90d8c30c7bbe0e72/%D1%82%D0%B5%D1%81%D1%82.zip"
            }
        ],
        "message_id": "e30e7aa3-f8b7-44ab-8c0c-3e990b42474a",
        "prev": "38a1e388-e26b-4844-a2f3-7e6c5e4528cb",
        "to": "g-3f7e2a85-49f5-4586-8229-d9c52813dcb2"
    }
}

Отправка аудиосообщения

POST /api/v3/teams/{team_uid}/messages/{chat_jid}?type=audiomsg

Пример запроса:

file: audiomsg.wav

Пример ответа:

{
    "_time": "1.1 s",
    "ok": true,
    "result": {
        "chat": "g-3f7e2a85-49f5-4586-8229-d9c52813dcb2",
        "chat_type": "group",
        "content": {
            "duration": 3,
            "mediaURL": "http://127.0.0.1:8000/u/b6186d0fb520492ea64f21ca6152bc5d/65e8b05d-fdf5-4a82-bc30-415f588576a6.mp3",
            "size": 606252,
            "text": "Аудиосообщение: http://127.0.0.1:8000/u/b6186d0fb520492ea64f21ca6152bc5d/65e8b05d-fdf5-4a82-bc30-415f588576a6.mp3",
            "type": "audiomsg"
        },
        "created": "2019-09-27T01:01:00.177963Z",
        "editable_until": "2019-09-28T01:01:00.177963Z",
        "from": "d-0b1b2362-fb69-4dd6-8bfb-90c89517168d",
        "gentime": 1569546060177981756,
        "is_last": true,
        "message_id": "65e8b05d-fdf5-4a82-bc30-415f588576a6",
        "prev": "e30e7aa3-f8b7-44ab-8c0c-3e990b42474a",
        "to": "g-3f7e2a85-49f5-4586-8229-d9c52813dcb2"
    }
}

История сообщений

content — само сообщение. Всегда имеет поля type и text. В зависимости от type может содержать много разных других интересных полей. Подробнее в разделе типы сообщений. Если клиент не знает, как обрабатывать конкретный type, он должен отобразить содержимое text.

read — прочитано ли сообщение тем, кто запрашивает эту информацию.

message_id — uuid сообщения.

is_first — флаг для упрощения догрузки при прокрутке. Если мы скроллим вверх, и наткнулись на первое соообщение, более раннюю историю запрашивать уже не надо.

chat_type — тип: "task", "group", "direct"

important – важное сообщение: "true" или "false" (по умолчанию)

linked_messages — список связанных (пересылаемых) сообщений.

links — Информация о ссылках в тексте. При этом null означает, что ссылок пока не обнаружено. Детектор ссылок работает фоном, и если находит ссылки, через server.message.update присылает модифицированное сообщение. Если детектор отработал, но ссылок так и не нашёл, в поле будет []. В общем случае клиенту должно быть всё равно на эти различия, но для отладки может пригодиться.

GET /api/v3/teams/{team_uid}/messages/{chat_jid}?limit=5

История сообщений. Отдаётся по 200 штук за раз.

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

  • ?old_from=[msgId] — показать пачку старых сообщений, начиная с msgId (но не включая его)
  • ?new_from=[msgId] — показать пачку новых сообщений, начиная с msgId (но не включая его)
  • ?old_from_inc=[msgId] — показать пачку старых сообщений, начиная с msgId (включая его)
  • ?new_from_inc=[msgId] — показать пачку новых сообщений, начиная с msgId (включая его)
  • ?limit=100 — отдавать не по 200, а по 100, например. Но больше 200 всё равно нельзя.
  • exact — id сообщения, которое вернуть
  • unread — true — возвращать только непрочитанные сообщения

Пример ответа:

{
    "_time": "64 ms",
    "ok": true,
    "result": {
        "messages": [
            {
                "chat": "g-3f7e2a85-49f5-4586-8229-d9c52813dcb2",
                "chat_type": "group",
                "content": {
                    "actor": "d-0b1b2362-fb69-4dd6-8bfb-90c89517168d",
                    "text": "Группа удалена",
                    "title": "Группа удалена",
                    "type": "change"
                },
                "created": "2019-09-27T01:00:55.501025Z",
                "from": "d-a2d94e8e-74aa-4b0b-b55d-0b4fc1ce07f4",
                "gentime": 1569546055501056735,
                "message_id": "cc8e9c13-4d18-479a-8109-82b7047d4e86",
                "prev": "2ffd70ba-dcba-4d24-88a8-c221256eba36",
                "to": "g-3f7e2a85-49f5-4586-8229-d9c52813dcb2"
            },
            {
                "chat": "g-3f7e2a85-49f5-4586-8229-d9c52813dcb2",
                "chat_type": "group",
                "content": {
                    "text": "Я яблоко зеленое, спелое, садовое.",
                    "type": "plain"
                },
                "created": "2019-09-27T01:00:59.030433Z",
                "editable_until": "2019-09-28T01:00:59.030433Z",
                "from": "d-0b1b2362-fb69-4dd6-8bfb-90c89517168d",
                "gentime": 1569546059030447528,
                "message_id": "38a1e388-e26b-4844-a2f3-7e6c5e4528cb",
                "prev": "cc8e9c13-4d18-479a-8109-82b7047d4e86",
                "to": "g-3f7e2a85-49f5-4586-8229-d9c52813dcb2"
            },
            {
                "chat": "g-3f7e2a85-49f5-4586-8229-d9c52813dcb2",
                "chat_type": "group",
                "content": {
                    "mediaURL": "http://127.0.0.1:8000/u/ed6fa57775db46ca90d8c30c7bbe0e72/%D1%82%D0%B5%D1%81%D1%82.zip",
                    "name": "тест.zip",
                    "size": 47132,
                    "text": "Видео: http://127.0.0.1:8000/u/ed6fa57775db46ca90d8c30c7bbe0e72/%D1%82%D0%B5%D1%81%D1%82.zip",
                    "type": "file"
                },
                "created": "2019-09-27T01:00:59.416504Z",
                "editable_until": "2019-09-28T01:00:59.416504Z",
                "from": "d-0b1b2362-fb69-4dd6-8bfb-90c89517168d",
                "gentime": 1569546059416728748,
                "links": [
                    {
                        "pattern": "http://127.0.0.1:8000/u/ed6fa57775db46ca90d8c30c7bbe0e72/%D1%82%D0%B5%D1%81%D1%82.zip",
                        "text": "127.0.0.1:8000/u/ed6fa57775db46ca90d8c30c7bbe0e72/%D1%82%D0%B...",
                        "url": "http://127.0.0.1:8000/u/ed6fa57775db46ca90d8c30c7bbe0e72/%D1%82%D0%B5%D1%81%D1%82.zip"
                    }
                ],
                "message_id": "e30e7aa3-f8b7-44ab-8c0c-3e990b42474a",
                "prev": "38a1e388-e26b-4844-a2f3-7e6c5e4528cb",
                "to": "g-3f7e2a85-49f5-4586-8229-d9c52813dcb2"
            },
            {
                "chat": "g-3f7e2a85-49f5-4586-8229-d9c52813dcb2",
                "chat_type": "group",
                "content": {
                    "duration": 3,
                    "mediaURL": "http://127.0.0.1:8000/u/b6186d0fb520492ea64f21ca6152bc5d/65e8b05d-fdf5-4a82-bc30-415f588576a6.mp3",
                    "size": 606252,
                    "text": "Аудиосообщение: http://127.0.0.1:8000/u/b6186d0fb520492ea64f21ca6152bc5d/65e8b05d-fdf5-4a82-bc30-415f588576a6.mp3",
                    "type": "audiomsg"
                },
                "created": "2019-09-27T01:01:00.177963Z",
                "editable_until": "2019-09-28T01:01:00.177963Z",
                "from": "d-0b1b2362-fb69-4dd6-8bfb-90c89517168d",
                "gentime": 1569546060177981756,
                "message_id": "65e8b05d-fdf5-4a82-bc30-415f588576a6",
                "prev": "e30e7aa3-f8b7-44ab-8c0c-3e990b42474a",
                "to": "g-3f7e2a85-49f5-4586-8229-d9c52813dcb2"
            },
            {
                "chat": "g-3f7e2a85-49f5-4586-8229-d9c52813dcb2",
                "chat_type": "group",
                "content": {
                    "duration": 27,
                    "mediaURL": "http://127.0.0.1:8000/u/617469fb8b2545bfb5409a0a53305de6/9f2c95dd-0589-4149-a15a-949c1464aa30.mp3",
                    "size": 5933055,
                    "text": "Аудиосообщение: http://127.0.0.1:8000/u/617469fb8b2545bfb5409a0a53305de6/9f2c95dd-0589-4149-a15a-949c1464aa30.mp3",
                    "type": "audiomsg"
                },
                "created": "2019-09-27T01:01:02.888433Z",
                "editable_until": "2019-09-28T01:01:02.888433Z",
                "from": "d-0b1b2362-fb69-4dd6-8bfb-90c89517168d",
                "gentime": 1569546062888466521,
                "is_last": true,
                "message_id": "9f2c95dd-0589-4149-a15a-949c1464aa30",
                "prev": "65e8b05d-fdf5-4a82-bc30-415f588576a6",
                "to": "g-3f7e2a85-49f5-4586-8229-d9c52813dcb2"
            }
        ]
    }
}

Фильтр сообщений

GET /api/v3/teams/{team_uid}/messages?has_upload=true&limit=5

Поиск сообщений. Используется пагинация limit/offset.

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

  • chat — jid собеседника, группы или задачи (через запятую)
  • sender — jid отправителей (через запятую)
  • chat_type - тип чата (через запятую): "task", "group", "direct". Имеет смысл только если нет параметра chat.
  • has_upload — "true" | "false" | "any". По умолчанию "any".
  • text – подстрока, не меньше 3 символов
  • type - тип сообщения (через запятую): "image", "video", "plain", "file"
  • important — если "true", то выдаст только важные сообщения. В противном случае все
  • date_from — дата, с которой показывать сообщения (включительно). Пример формата: '2017-12-31'. Можно передать и время: '2017-01-01 00:10:00'
  • date_to — дата, до которой показывать сообщения

Пример ответа:

{
    "_time": "239 ms",
    "ok": true,
    "result": {
        "count": 2,
        "limit": 5,
        "objects": [
            {
                "chat": "g-3f7e2a85-49f5-4586-8229-d9c52813dcb2",
                "chat_type": "group",
                "content": {
                    "duration": 27,
                    "mediaURL": "http://127.0.0.1:8000/u/617469fb8b2545bfb5409a0a53305de6/9f2c95dd-0589-4149-a15a-949c1464aa30.mp3",
                    "size": 5933055,
                    "text": "Аудиосообщение: http://127.0.0.1:8000/u/617469fb8b2545bfb5409a0a53305de6/9f2c95dd-0589-4149-a15a-949c1464aa30.mp3",
                    "type": "audiomsg"
                },
                "created": "2019-09-27T01:01:02.888433Z",
                "editable_until": "2019-09-28T01:01:02.888433Z",
                "from": "d-0b1b2362-fb69-4dd6-8bfb-90c89517168d",
                "gentime": 1569546062888466521,
                "is_last": true,
                "message_id": "9f2c95dd-0589-4149-a15a-949c1464aa30",
                "prev": "65e8b05d-fdf5-4a82-bc30-415f588576a6",
                "to": "g-3f7e2a85-49f5-4586-8229-d9c52813dcb2"
            },
            {
                "chat": "g-3f7e2a85-49f5-4586-8229-d9c52813dcb2",
                "chat_type": "group",
                "content": {
                    "comment": "кремлевский спуск если бы я выдвинулась",
                    "duration": 3,
                    "mediaURL": "http://127.0.0.1:8000/u/b6186d0fb520492ea64f21ca6152bc5d/65e8b05d-fdf5-4a82-bc30-415f588576a6.mp3",
                    "size": 606252,
                    "text": "Аудиосообщение: http://127.0.0.1:8000/u/b6186d0fb520492ea64f21ca6152bc5d/65e8b05d-fdf5-4a82-bc30-415f588576a6.mp3",
                    "type": "audiomsg"
                },
                "created": "2019-09-27T01:01:00.177963Z",
                "editable_until": "2019-09-28T01:01:00.177963Z",
                "from": "d-0b1b2362-fb69-4dd6-8bfb-90c89517168d",
                "gentime": 1569546063078567570,
                "message_id": "65e8b05d-fdf5-4a82-bc30-415f588576a6",
                "prev": "e30e7aa3-f8b7-44ab-8c0c-3e990b42474a",
                "to": "g-3f7e2a85-49f5-4586-8229-d9c52813dcb2"
            }
        ],
        "offset": 0
    }
}