Описание 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