Описание REST API для подключения к боту Dina

Используйте простой REST API для подключения к боту Дина разнообразных приложений, содержащих задачи. Мы также будем постепенно расширять перечень подключаемых к Дине приложений и публиковать их на сайте. Следите за новостями.

Если вам нужна помощь в подключении вашей системы задач, напишите нам по адресу info@dinabot.com и мы с радостью вам поможем.

Описание REST API

Базовый URI: https://dinabot.azurewebsites.net/api/[command], где [command] — команда.

Список поддерживаемых команд:

  1. ping — пинг, можно использовать для проверки Токена;
  2. members — запросить список пользователей вашего группового канала;
  3. request — запустить новый запрос (опрос) пользователей;
  4. stoprequest — остановить опрос пользователей по задачам и получить результаты;
  5. inform — проинформировать пользователей по их текущим задачам.

Получение Токена доступа к API

Для доступа к API используется Токен доступа, который для вас генерирует бот Дина. Токен всегда является параметром HTTPS запроса и указывается после названия команды. Пример: https://dinabot.azurewebsites.net/api/request?token=97e5db6f345311ee1cac1af5225a9422

  1. Подключите бота Дину в своем мессенджере
    • Смотрите как подключить в Skype здесь;
    • Смотрите как подключить в Telegram здесь;
    • Смотрите как подключить в Whatsapp здесь;
  2. Отправьте боту Дине в личном чате сообщение «gettoken»
  3. В ответ бот Дина пришлет ваш Токен доступа.
  4. Скопируйте Токен доступа и используйте для подключения к 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