Описание REST API для подключения к боту Dina
Используйте простой REST API для подключения к боту Дина разнообразных приложений, содержащих задачи. Мы также будем постепенно расширять перечень подключаемых к Дине приложений и публиковать их на сайте. Следите за новостями.
Если вам нужна помощь в подключении вашей системы задач, напишите нам по адресу info@dinabot.com и мы с радостью вам поможем.
Описание REST API
Базовый URI: https://dinabot.azurewebsites.net/api/[command], где [command] – команда.
Список поддерживаемых команд:
- ping – пинг, можно использовать для проверки Токена;
- members – запросить список пользователей вашего группового канала;
- request – запустить новый запрос (опрос) пользователей;
- stoprequest – остановить опрос пользователей по задачам и получить результаты;
- inform – проинформировать пользователей по их текущим задачам.
Получение Токена доступа к API
Для доступа к API используется Токен доступа, который для вас генерирует бот Дина. Токен всегда является параметром HTTPS запроса и указывается после названия команды. Пример: https://dinabot.azurewebsites.net/api/request?token=97e5db6f345311ee1cac1af5225a9422
- Подключите бота Дину в своем мессенджере
- Смотрите как подключить в Skype здесь;
- Смотрите как подключить в Telegram здесь;
- Смотрите как подключить в Whatsapp здесь;
- Отправьте боту Дине в личном чате сообщение “gettoken”
- В ответ бот Дина пришлет ваш Токен доступа.
- Скопируйте Токен доступа и используйте для подключения к API
Описание команд
Команда ping
Описание: пинг сервиса, можно использовать для проверки Токена
Метод: GET
Параметры:
- token – Токен доступа
Ответ:“OK” – если есть доступ к API
Пример: GET https://dinabot.azurewebsites.net/api/ping?token=97e5db6f345311ee1cac1af5225a9422
Команда members
Описание: запросить список пользователей группового канала
ВНИМАНИЕ! Бот выводит только тех пользователей, которые добавили его в свои контакты. Только их он может опрашивать. Остальные пользователи канала ботом не видны и использоваться не могут.
Проверить каких пользователей в канале бот знает, можно отправив боту сообщение “members” в групповом канале. В ответ он выведет список тех кого знает .
Метод: GET
Параметры:
- token – Токен доступа
- channel – имя вашего группового канала, для которого требуется получить список пользователей
Ответ:массив JSON объектов следующей структуры:
[ { “id”: “ИД пользователя”,
“name”: ”Имя пользователя”,
"channelid": "Имя мессенджера",
"locale": "локаль пользователя",
"timezone": "Временная зона пользователя”
},
…
]
Пример: GET https://dinabot.azurewebsites.net/api/members?token=97e5db6f345311ee1cac1af5225a9422&channel=DinabotTest
Команда request
Описание: запустить новый опрос по задачам пользователей в чате
Метод: POST
Тип: ‘application/json’
Параметры:
- token – Токен доступа
Тело запроса: JSON объект, содержащий параметры запроса. Структура объекта:
{ “channel”: “Имя канала”, //имя канала, в рамках которого производится запрос
“type”: “tasks_state”, //тип опроса, сейчас поддерживается только tasks_state
“sourse”: “Имя источника запроса” //это может быть ссылка на Google таблицу, или ссылка на ваш сервис.
“title”: “Тема опроса”, //бот использует ее при опросе. Н-р “Еженедельный статус”
“timeout”: 30, //таймаут длительности опроса в минутах. После этого опрос будет считаться завершенным
“state_map”: //это карта переходов по статусам и правила их отработки. JSON объект в формате:
{“Имя статуса”: //Имя статуса для которого указываем правила, далее идут правила
{ “Имя следующего статуса”: “Yes”, //Yes - возможен переход,
“Имя след статуса 2”: “No”, //No-не возможен переход,
“Имя след статуса 3”: “Ask note”, //Ask note - запрашивать комментарий при указании этого статуса
“Имя след статуса 4”: “Ask %”, //Ask % - запрашивать % выполнения задачи при указании этого статуса
“Имя след статуса 5”: “Ask hrs”, //Ask hrs - запрашивать фактические трудозатраты на выполнение задачи при указании этого статуса
…
},
....
}, //закончилась карта переходов по статусам
“tasks”:[{ //массив задач, по которым опрашиваем пользователей в этом запросе.
“number”: “номер задачи”, //номер задачи, не обязательно
“title”: “тема задачи”, //тема, или краткое содержание задачи (ОБЯЗАТЕЛЬНО!)
“description”: “Подробное описание задачи”, //НЕ ОБЯЗАТЕЛЬНО
“assigned”: ”ИД кому назначена задача”, //кому назначена задача, у кого производить опрос. Строго должно быть равно ид пользователя, которые выдает бот по команде members
“due”: Срок задачи, //JSON дата
“priority”: “Приоритет”, //приоритет задачи, произвольное поле, указывается в опросе.
state: “Текущее состояние задачи” //бот его указывает при опросе
}
…
]
}
Ответ: JSON объект содержащий id запроса, который потом используется при получении результатов:
{“requestid”:”ид опроса”}
Пример: POST https://dinabot.azurewebsites.net/api/request?token=97e5db6f345311ee1cac1af5225a9422
Команда stoprequest
Описание: остановить опрос пользователей в чате и получить результаты.
Метод: GET
Параметры:
- token – Токен доступа
- requestid – ид запроса, которое было выдано при выполнении команды request.
Ответ: JSON объект следующей структуры:
{"requestid":"ид запроса",
"results":[ //массив результатов опроса
{"requestid":"ид запроса",
"id":"ид вопроса",
"row":5, //номер строки в массиве задач исходного запроса
"number": "номер задачи ", //если был в исходном запросе
"title": "Краткое описание задачи",
"state": "Исходный статус",
"description": "Описание задачи ", //если было в исходном запросе
"due": "2019-04-20T21:00:00.000Z", //Срок задачи
"priority": "Высокий", //Приоритет задачи
"answer": "Закрыто", //Ответ пользователя, с новым статусом
"note": "Комментарий пользователя", //если было правило Asc note для указанного им статуса
"new_percent": 30, //ответ пользователя в части % выполнения, если было правило Asc % для указанного им статуса
"new_actual_hours": 13, //ответ пользователя в части факт трудозатрат на выполнение, если было правило Asc hrs для указанного им статуса
"answer_date":"2019-04-20T15:16:10.764Z"}, //дата и время ответа пользователя
},
//следующие задачи
…
]
}
Пример: GET https://dinabot.azurewebsites.net/api/stoprequest?token=97e5db6f345311ee1cac1af5225a9422&requestid =1234312