Справка

Документация по API

Здесь вы можете прочитать документация по AssistBot API.

Description

The AssistBot API organized around REST. All requests must be sent using POST method with form-encoded parameters. API returns JSON encoded responses.

The AssistBot API uses API key to authenticate requests. Each request must contain Authorization header with provided API key. You can get this key from the company settings page in AssistBot admin panel.

Please, do not share your API key in publicity access such as GitHub, client-side code etc.

Response attributes

  • data object or array

    Contains main data related to requested endpoint.

  • count integer

    This attribute appears only if "data" attribute presented as array. Shows amount of elements in response.

  • status boolean

    Indicates is request was successful.

BASE URL
https://api.assist-bot.com
REQUEST EXAMPLE
Node.js
const axios = require('axios');
const key = 'Your API key';

function MakeRequest(data, ep) {
   axios({
      method: 'post',
      url: 'https://api.assist-bot.com'+ep,
      data,
      headers: {
         'Content-Type': 'application/json',
         'Authorization': 'Bearer '+key,
      }
   })
   .then(res=>{
      console.log(res.data)
   })
   .catch(err=>{
      console.log(err)
   })
}

const parameters = {
   foo1: 'bar1',
   foo2: 'bar2',
};

MakeRequest(parameters, '/v1/endpoint');
RESPONSE
JSON
{
   data: [],
   count: 0,
   status: true
}

Getting company info

Get information about your company, API key of which you using.

Response attributes

  • name string

    Company name

  • logo string or null

    URL to a logo. NULL if logo doesn't uploaded.

  • code string

    Unique company ID.

  • work_start_time string

    Work start time.

  • work_end_time string

    Work end time.

  • work_days array

    Working days of week. 0 - Monday, 1 - Tuesday etc.

  • timezone string

    Company time zone.

  • bot_lang string

    Chat bot language.

  • app string or null

    Name of linked application. NULL if application doesn't linked.

  • hook_url string or null

    Webhooks endpoint URL. NULL if webhook endpoint doesn't specified.

  • bot_enabled boolean

    Is bot enabled for the company.

  • motiv_enabled boolean

    Is motivation collecting enabled for the company administrators.

  • auto_accept boolean

    Is automatic members adding enabled.

  • create_dt integer

    UTC timestamp of company creation.

POST /v1/company/info
Node.js
const parameters = {};

MakeRequest(parameters, '/v1/company/info');
RESPONSE
JSON
{
   data: {
      name: 'My company',
      logo: 'https://static.assist-bot.com/images/image.png',
      code: '012345',
      work_start_time: '09:00',
      work_end_time: '18:00',
      work_days: [ 0, 1, 2, 3, 4 ],
      timezone: 'America/New_York',
      bot_lang: 'en',
      app: 'tg',
      hook_url: null,
      bot_enabled: true,
      motiv_enabled: true,
      auto_accept: false,
      create_dt: 1603789922
   },
   status: true
}

Getting company departments

Get departments from company based on filtering parameters.

Request parameters

  • department_id integer or array

    Optional. Departments ids.

  • creator_id integer or array

    Optional. Member id who created the department.

Response attributes

  • id integer

    Department id.

  • title string

    Department name.

  • default boolean

    Is department a default ("All members" department).

  • created_by integer or null

    Id of member who created the department. NULL if department is default.

  • create_dt integer

    UTC timestamp of department creation.

  • check_motivation boolean

    Is motivation collecting enabled.

  • motivationd_days array

    Days of week for motivation collecting. 0 - Monday, 1 - Tuesday etc.

  • users array

    Users ids who added to this department.

POST /v1/company/departments
Node.js
const parameters = {
   department_id: [1],
   creator_id: [1]
};

MakeRequest(parameters, '/v1/company/departments');
RESPONSE
JSON
{
   data: [
      {
         id: 1,
         title: 'Sales department',
         default: true,
         created_by: 1,
         create_dt: 1603789922,
         check_motivation: false,
         motivation_days: [ 0 ],
         users: [ 1 ]
      }
   ],
   count: 1,
   status: true
}

Getting company users

Get users from company based on filtering parameters.

Request parameters

  • member_id integer or array

    Optional. Member ids.

  • role integer or array

    Optional. Role of members. 0 - Worker, 1 - Manager, 2 - Administrator.

  • active boolean

    Optional. Is member active.

  • accepted boolean

    Optional. Is member added to company.

Response attributes

  • id integer

    Member id.

  • email string

    Member's email.

  • name string or null

    Member's name. NULL if name doesn't specified.

  • nickname string or null

    Member's nickname in linked application. NULL if nickname doesn't exists.

  • photo string or null

    URL to member's photo. NULL if photo doesn't uploaded.

  • role integer

    Member's role.

  • position string or null

    Member's position. NULL if position doesn't specified.

  • app string or null

    Member's linked application. NULL if application doesn't linked.

  • accepted boolean

    Is member added to company.

  • active boolean

    Is member active.

POST /v1/company/members
Node.js
const parameters = {
   member_id: [1],
   role: 2,
   active: true,
   accepted: true,
};

MakeRequest(parameters, '/v1/company/members');
RESPONSE
JSON
{
   data: [
      {
         id: 1,
         email: 'johndoe@company.com',
         name: null,
         nickname: null,
         photo: 'https://static.assist-bot.com/images/photo.jpg',
         role: 2,
         position: null,
         app: null,
         accepted: true,
         active: true
      }
   ],
   count: 1,
   status: true
}

Getting templates

Get template elements based on filtering parameters.

Request parameters

  • template_id integer or array

    Optional. Template ids.

  • creator_id integer or array

    Optional. Member id who created the template.

Response attributes

  • id integer

    Template id.

  • title string

    Template name.

  • intro string or null

    Template intro text. NULL if intro doesn't specified.

  • outro string or null

    Tempalte putro text. NULL if outro doesn't specified.

  • description string

    Template description.

  • files_allowed boolean

    Is files attaching allowed.

  • file_offer string or null

    Text offer for file attaching. NULL of text doesn't specified.

  • create_dt integer

    UTC timestamp of template creation.

  • questions array

    Object contains data about tempalate questions.

  • questions[x].id integer

    Question id.

  • questions[x].question string

    Question full text

  • questions[x].short_question string

    Question short text.

  • questions[x].blocker boolean

    Is question a blocker.

  • questions[x].answer_type string

    Defined type of answer for this question. Can be "txt", "num", "opt" or "noa".

  • questions[x].options array or null

    Options for "opt" type. NULL if "answer_type" attribute not "opt".

  • questions[x].image string or null

    URL to image attached to the question. NULL if image doesn't attached.

  • questions[x].color string or null

    Color applied to the question. NULL if color doesn't applied.

  • created_by integer

    UTC timestamp of template creation.

  • used_times integer

    By how many standups this template is used.

POST /v1/elements/templates
Node.js
const parameters = {
   template_id: [1],
   creator_id: [1],
};

MakeRequest(parameters, '/v1/elements/templates');
RESPONSE
JSON
{
   data: [
      {
         id: 1,
         title: 'Daily questions',
         intro: null,
         outro: null,
         description: 'Questions for the daily standup',
         files_allowed: false,
         file_offer: null,
         create_dt: 1599134450,
         questions: [
            {
               id: 10,
               question: 'What did you do yesterday?',
               short_question: 'Yesterday work',
               blocker: false,
               answer_type: 'txt',
               options: null,
               image: null,
               color: 'black',
            },
            {
               id: 11,
               question: 'Any blockers?',
               short_question: 'Blockers',
               blocker: true,
               answer_type: 'opt',
               options: [ 'No', 'Yes', 'Probably' ],
               image: null
            },
         ],
         created_by: 1,
         used_times: 1
      }
   ],
   count: 1,
   status: true
}

Getting standups

Get standup elements based on filtering parameters.

Request parameters

  • standup_id integer or array

    Optional. Standups ids.

  • creator_id integer or array

    Optional. Member id who created the standup.

  • department_id integer or array

    Optional. Ids of departments that linked to the standup.

  • status integer or array

    Optional. Status of standup. 0 - draft, 1 - active.

Response attributes

  • id integer

    Standup id.

  • title string

    Standup name.

  • departments_id array

    Ids of departments that linked to the standup.

  • status integer

    Standup status.

  • create_dt integer

    UTC timestamp of standup creation.

  • created_by integer

    Member id who created the standup.

  • template_id integer

    Template id linked to the standup.

  • frequency integer

    Frequency of standup launching. 0 - weekly, 1 - every 2 weeks, 2 - every 3 weeks, 3 - every 4 weeks.

  • days array

    Days of standup launching. 0 - Monday, 1 - Tuesday etc.

  • time string

    Time of standup launching.

  • time_limit string

    Allowable time limit for getting responses.

  • anonymous boolean

    Is standup anonymous.

  • use_working_days boolean

    Is standup uses working days of members.

  • use_vacation boolean

    Is standup uses vacation days of members.

  • use_timezones boolean

    Is standup uses time zones of members.

  • use_start_time boolean

    Is standup launches at member's work start time.

  • email_reports boolean

    Is email reports enabled.

  • show_blockers boolean

    Is blockers displays in channel.

  • channel string, integer or null

    Channel for results. Type of result depends on linked application. NULL if channel doesn't specified.

  • launch_dt integer or null

    UTC timestmp of last launching. NULL if standup doesn't launched yet.

POST /v1/elements/standups
Node.js
const parameters = {
   standup_id: [1],
   creator_id: [1],
   department_id: [1],
   status: [0],
};

MakeRequest(parameters, '/v1/elements/standups');
RESPONSE
JSON
{
   data: [
      {
         id: 1,
         title: 'Daily standup',
         departments_id: [ 1 , 2 ],
         status: 0,
         create_dt: 1599147607,
         created_by: 1,
         template_id: 1,
         frequency: 0,
         days: [ 0, 1, 2, 3, 4 ],
         time: '16:30',
         time_limit: '02:00',
         anonymous: false,
         use_working_days: false,
         use_vacation: false,
         use_timezones: false,
         use_start_time: false,
         show_blockers: false,
         channel: null,
         launch_dt: null
      }
   ],
   count: 1,
   status: true
}

Getting tasks

Get task elements based on filtering parameters.

Request parameters

  • task_id integer or array

    Optional. Tasks ids.

  • creator_id integer or array

    Optional. Member id who created the task.

  • status integer or array

    Optional. Status of task. 0 - draft, 1 - active.

Response attributes

  • id integer

    Task id.

  • title string

    Task name.

  • description string

    Task description.

  • frequency integer

    Task reminder frequency. 0 - weekly, 1 - every 2 weeks, 2 - every 3 weeks, 3 - every 4 weeks.

  • days array

    Task reminder days. 0 - Monday, 1 - Tuesday etc.

  • time string

    Task reminder time.

  • use_working_days boolean

    Is task uses working days of members.

  • use_vacation boolean

    Is task uses vaction days of members.

  • use_timezones boolean

    Is task uses time zones of members.

  • email_reports boolean

    Is email reports enabled

  • status integer

    Task status. 0 - draft, 1 - active.

  • created_by integer

    Member id who created the task.

  • create_dt integer

    UTC timestamp of task creation.

  • launch_dt integer

    UTC timestamp of task launching.

  • steps array

    Object conatining task items.

  • steps[x].id integer

    Task item id

  • steps[x].title string

    Task item title.

  • steps[x].ended_by integer or null

    Member id who completed or canceled the task item. NULL if step doesn't completed of canceled.

  • steps[x].end_dt integer or null

    UTC timestamp of completion or canceling the task item. NULL if step doesn't completed of canceled.

  • steps[x].member_id integer

    Member id who is charge for this task item.

  • steps[x].canceled boolean

    Is this task item canceled.

  • steps[x].deadline string or null

    Deadline as UTC timestamp. NULL if task item doesn't has deadline.

  • channel string, integer or null

    Channel for results. Type of result depends on linked application. NULL if channel doesn't specified.

POST /v1/elements/tasks
Node.js
const parameters = {
   task_id: [1],
   creator_id: [1],
   status: [0]
};

MakeRequest(parameters, '/v1/elements/tasks');
RESPONSE
JSON
{
   data: [
      {
         id: 1,
         title: 'Complete the project',
         description: 'Complete the project and deploy it in public access.',
         frequency: 0,
         days: [ 0, 1, 2, 3, 4 ],
         time: '15:45',
         use_working_days: false,
         use_vacation: false,
         use_timezones: false,
         email_reports: false,
         status: 2,
         created_by: 1,
         create_dt: 1602676973,
         launch_dt: 1602676980,
         steps: [
            {
               id: 19,
               title: 'Finish programming',
               ended_by: 1,
               end_dt: 1599742915,
               member_id: 2,
               canceled: false,
               deadline: false
            },
            {
               id: 20,
               title: 'Deploy project',
               ended_by: 1,
               end_dt: 1599743441,
               member_id: 1,
               canceled: false,
               deadline: false
            },
         ],
         channel: null
      }
   ],
   count: 1,
   status: true
}

Getting polls

Get poll elements based on filtering parameters.

Request parameters

  • poll_id integer or array

    Optional. Polls ids.

  • creator_id integer or array

    Optional. Member id who created the poll.

Response attributes

  • id integer

    Poll id.

  • title string

    Poll name.

  • description string

    Poll description.

  • intro string or null

    Poll intro text. NULL if intro doesn't specified.

  • outro string or null

    Poll outro text. NULL if outro doesn't specified.

  • departments_id array

    Ids of departments that linked to the poll.

  • create_dt integer

    UTC timestamp of the poll creation.

  • launch_times integer

    How many times the poll was launched.

  • options array

    Object containing poll options data.

  • options[x].id integer

    Option id.

  • options[x].title string

    Option text.

  • options[x].image string or null

    URL to image attached to the option. NULL if image doesn't attached.

  • created_by integer

    Member id who created the poll.

POST /v1/elements/polls
Node.js
const parameters = {
   poll_id: [1],
   creator_id: [1]
};

MakeRequest(parameters, '/v1/elements/polls');
RESPONSE
JSON
{
   data: [
      {
         id: 1,
         title: 'Vacation poll',
         description: 'Where do you spend your vacation?',
         intro: null,
         outro: null,
         departments_id: [ 1 ],
         create_dt: 1600158959,
         launch_times: 2,
         options: [
            {
               id: 10,
               title: 'At home',
               image: null,
            },
            {
               id: 11,
               title: 'Abroad',
               image: null,
            },
            {
               id: 12,
               title: 'I don't know yet',
               image: null,
            }
         ],
         created_by: 1
      }
   ],
   count: 1,
   status: true
}

Getting standup history

Get standup reports history based on filtering parameters.

Request parameters

  • standup_id integer

    Required. Standup id.

  • member_id integer or array

    Optional. Ids of members what submitted reports.

  • department_id integer or array

    Optional. Ids of departments that linked to standups.

  • from string

    Optional. Date in YYYY-MM-DD format from which you want to retrieve the history. For example: 2020-08-25.

  • to string

    Optional. Date in YYYY-MM-DD format untill which you want to retrieve the history. For example: 2020-08-27.

  • timezone string

    Optional. Time zone in TZ database format in which you specified dates in "from" and "to" parameters. By default using your company's time zone. For example: America/New_York.

Response attributes

  • id integer

    Report id

  • standup_id integer

    Standup id

  • standup_name integer

    Standup name.

  • member_id integer

    Member id who submitted the report.

  • departments_id array

    Ids of departments that linked to the standup.

  • launch_dt integer

    UTC timestamp of report sending.

  • questions array

    Object containing standup questions data.

  • questions[x].id integer

    Question id

  • questions[x].title string

    Question text.

  • questions[x].blocker boolean

    Is question a blocker.

  • questions[x].answer_type string

    Defined type of answer for this question. Can be "txt", "num" or "opt".

  • file_url string or null

    URL to attached file to the report. NULL if file doesn't attached.

  • file_name string or null

    Original name of the attached file. NULl if file doesn't attached.

  • responses array

    Object containing member's responses data.

  • responses[x].id integer

    Response id.

  • responses[x].question_id integer

    Question id for this response.

  • responses[x].answer string or null

    Member's response text. If question for this response is blocker and member skipped it, response will be "no".

  • responses[x].send_dt integer

    UTC timestamp of question sending.

  • responses[x].answer_dt integer or null

    UTC timestamp of response submitting.

POST /v1/history/standups
Node.js
const parameters = {
   report_id: 1,
   member_id: [2],
   department_id: [1, 2],
   from: '2020-08-25', 
   to: '2020-08-27',
   timezone: 'America/New_York',
};

MakeRequest(parameters, '/v1/history/standups');
RESPONSE
JSON
{
   data: [
      {
         id: 12,
         standup_id: 1,
         standup_name: 'Daily standup',
         member_id: 2,
         departments_id: [ 2 ],
         launch_dt: 1599743728,
         questions: [
            {
               id: 73,
               title: 'What did you do yesterday?',
               blocker: false,
               answer_type: 'txt'
            },
            {
               id: 74,
               title: 'Any blockers?',
               blocker: true,
               answer_type: 'opt'
            },
         ],
         file_url: 'https://static.assist-bot.com/files/ga5utf8b2wfd4xupxakbjmczttzgxw0k.zip',
         file_name: 'package.zip',
         responses: [
            {
               id: 342,
               question_id: 73,
               answer: 'A lot of work',
               send_dt: 1599743766,
               answer_dt: 1599743792
            },
            {
               id: 343,
               question_id: 74,
               answer: 'Probably',
               send_dt: 1599743776,
               answer_dt: 1599743802
            }
         ]
      }
   ],
   count: 1,
   status: true
}

Getting poll history

Get poll responses history based on filtering parameters.

Request parameters

  • poll_id integer

    Required. Poll id.

  • department_id integer or array

    Optional. Ids of departments that linked to poll.

  • from string

    Optional. Date in YYYY-MM-DD format from which you want to retrieve the history. For example: 2020-08-25.

  • to string

    Optional. Date in YYYY-MM-DD format untill which you want to retrieve the history. For example: 2020-08-27.

  • timezone string

    Optional. Time zone in TZ database format in which you specified dates in "from" and "to" parameters. By default using your company's time zone. For example: America/New_York.

Response attributes

  • id integer

    Poll history id.

  • title string

    Poll name.

  • poll_id integer

    Poll id.

  • department_id integer

    Ids of departments that are involved in polling.

  • members_amount integer

    Amount of members involved in polling.

  • launch_dt integer

    UTC timestamp of the poll launching for this history item.

  • options array

    Object containing poll options data.

  • options[x].id integer

    Option id.

  • options[x].title string

    Option text.

  • options[x].stats integer

    Amount of votes for the option.

POST /v1/history/polls
Node.js
const parameters = {
   poll_id: 1,
   department_id: [1, 2],
   from: '2020-08-25', 
   to: '2020-08-27',
   timezone: 'America/New_York',
};

MakeRequest(parameters, '/v1/history/polls');
RESPONSE
JSON
{
   data: [
      {
         id: 7,
         title: 'Vacation poll',
         poll_id: 1,
         department_id: 2,
         members_amount: 1,
         launch_dt: 1602677018,
         options: [
            {
               id: 1,
               title: 'At home',
               stats: 1
            },
            {
               id: 2,
               title: 'Abroad',
               stats: 0
            },
            {
               id: 3,
               title: 'I don't know yet',
               stats: 0
            },
         ]
      }
   ],
   count: 1,
   status: true
}

Errors

Error codes description.

Response attributes

  • error object

    Object containing information about error.

  • error.code integer

    Error code.

  • error.message string

    Short message with error description.

  • status boolean

    Indicates is request was successful.

ERROR SAMPLE
JSON
{
   error: {
      code: 500,
      message: 'Server error'
   }, 
   status: false
}
ERROR CODES
JSON
100   Authorization token is not provided

101   Invalid authorization token

102   Not enough rights to access the API

200   Missing parameter

201   "From" date should be equal or before "To" date

202   Incorrect timezone

203   "From" and "To" dates together are required

204   Element id is required

500   Server error

501   Endpoint not found