ConnectNow Queue API Documentation

Welcome to the Queue System developer-guide API docs!

IMPORTANT

Make sure to familiarize yourself with the API philosophy before proceeding with this guide.

WARNING

This documentation is a work in progress.

Authentication

See: API Philosophy - authentication

Response Status Codes

See: API Philosophy - status codes

Blacklist hours of operation

Companies

Get all public companies

Authentication: You need to be logged in to access this resource.

Authorization: If you do not have god-permissions, you will only be able to list all public companies you are a member of.

GET /api/companies

Parameter	Type	Rules	Default	Description
with	array	Can be any combination of: users, queues, skills, companyUsers	-	What related objects to append to the JSON response

Create a company

Authentication: You need to be logged in to access this resource.

Authorization: You must be authorized to access this resource.

POST /api/companies

Parameter	Type	Rules	Required	Default	Description
name	string	Text	✅	-	The name of the company
slug	string	Text	✅	-	The unique identifying name for this company (text will be converted to slug)
logo_url	string	Valid URL to a JPG, PNG, or SVG image	✅	-	A URL to a logo image
query_expiry_time_in_minutes	integer	Number from 0 to 65535	-	60	The time it takes for a query to expire

Get a single company

GET /api/companies/{company-id}

Parameter	Type	Rules	Default	Description
with	array	Can be any combination of: users, queues, skills, companyUsers	-	What related objects to append to the JSON response

Sample response:

{
  "id": 1,
  "name": "Company Name",
  "slug": "company",
  "logo_url": "https:\/\/public.company.com\/logo.svg",
  "created_at": "2021-07-05T09:31:38.000000Z",
  "updated_at": "2021-07-05T09:31:38.000000Z"
}

Edit a single company

Authorization required

User must be authenticated and have access to the company.

All authorization requests require you to first be authenticated.

PUT /api/companies/{company-id}

Parameter	Type	Rules	Required	Default	Description
name	string	-	✅	-	The name of the company
slug	string	Text, all lower case with no spaces	-	-	The unique identifying name for this company
logo_url	string	Valid URL to a JPG, PNG, or SVG image	-	-	A URL to a logo image
query_expiry_time_in_minutes	integer	Number from 0 to 65535	-	60	The time it takes for a query to expire

Delete a single company

Authorization required

User must be authenticated and have access to the company.

All authorization requests require you to first be authenticated.

DELETE /api/companies/{company-id}

Company users

Get all company users

Authorization required

User must be authenticated. In addition, you must pass company_ids to companies you have access to in order to list the users in those companies.

All authorization requests require you to first be authenticated.

GET /api/company-users

Parameter	Type	Rules	Default	Description
with	array	Can be any combination of: user, personalQueue, company, skills, answeredQueries	-	What related objects to append to the JSON response
scopes	array	Can be any combination of: available, active, withinMaxOngoingQueryLimits, canTakeQuery, manager	-	What scopes to apply to the query

Sample response:

[
  {
    "id": 1,
    "user_id": 1,
    "company_id": 1,
    "created_at": "2021-07-05T09:31:38.000000Z",
    "accepted_at": "2021-07-05T09:36:11.000000Z",
    "invited_email": "hans.schmidt@domain.com",
    "max_ongoing_queries_handled": 3,
    "is_auto_max_number_handled": false,
    "ability_to_pick_from_queue": true,
    "is_auto_ability_to_pick_from_queue": false,
    "role": "agent",
    "is_active": true
  },
  {
    "id": 2,
    "user_id": 2,
    "company_id": 1,
    "created_at": "2021-07-10T13:12:22.000000Z",
    "accepted_at": "2021-07-10T13:13:50.000000Z",
    "invited_email": "sakura.watanabe@domain.com",
    "max_ongoing_queries_handled": 1,
    "is_auto_max_number_handled": true,
    "ability_to_pick_from_queue": false,
    "is_auto_ability_to_pick_from_queue": true,
    "role": "agent",
    "is_active": false
  }
  ...
]

Get a single company user

Authorization required

User must be authenticated and have the right to list the user (belonging to the same company).

All authorization requests require you to first be authenticated.

GET /api/company-users/{company-user-id}

Sample response:

{
  "id": 1,
  "user_id": 1,
  "company_id": 1,
  "created_at": "2021-07-05T09:31:38.000000Z",
  "accepted_at": "2021-07-05T09:36:11.000000Z",
  "invited_email": "hans.schmidt@domain.com",
  "max_ongoing_queries_handled": 3,
  "is_auto_max_number_handled": false,
  "ability_to_pick_from_queue": true,
  "is_auto_ability_to_pick_from_queue": false,
  "role": "agent",
  "is_active": true
}

Create a single company user

Authorization required

User must be authenticated and have rights for the company.

All authorization requests require you to first be authenticated.

POST /api/company-users

Parameter	Type	Rules	Required	Default	Description
user_id	integer	A valid user ID	-	-	The ID of the user this company belongs to. This is nullable to facilitate inviting a user to the company who is not yet registered
company_id	integer	A valid company ID	✅	-	The ID of the company this company user belongs to
invited_email	integer	A valid email address	✅	-	The email of the invited user
max_ongoing_queries_handled	integer	A valid integer	✅	1	The number of simultaneous queued queries this user can handle
is_auto_max_number_handled	boolean	true or false	✅	true	Whether this user's simultaneous handle limit is manually set, or managed by the system. The system may change this value based on the user's performance and achievements.
ability_to_pick_from_queue	boolean	true or false	✅	false	Whether this company user can choose which queries to answer from the queue
is_auto_ability_to_pick_from_queue	boolean	true or false	✅	true	Whether this user's ability to choose which query they answer is manually set, or managed by the system. The system may change this value based on the user's performance and achievements.
role	string	A valid role (agent, staffing_manager, or manager)	✅	agent	The access level for this company user
is_active	boolean	true or false	✅	true	Whether this company user is active or not. See: Billing - active users)

When creating a user, a personal queue is also created. See: Concept Overview - personal queues). In addition, a default user state is also created, with is_available set to 0 (false). Lastly, an invitation email is sent to the invited_email.

Company user skills

Get all company user skills

Append the skills data object when requesting a company user.

Company user states

The state of a given user in a company (a company user) determines if they are available to get and answer new queries.

Get all company user states

GET /api/company-user-states

Company user queues

Get a company users queues

Authorization required

User must be authenticated and have the right to list the user (belonging to the same company).

All authorization requests require you to first be authenticated.

GET /api/company-users/{company-user-id}/queues

Sample response:

{
  "queues": [
    {
      "id": 1,
      "name": "IT Queue",
      "company_id": 1,
      "company_user_id": null,
      "is_active": 1,
      "priority_delay_in_seconds": 60,
      "created_at": "2021-09-01T12:31:19.000000Z",
      "updated_at": "2021-09-01T12:31:19.000000Z",
      "deleted_at": null,
      "skills": [
        {
          "id": 1,
          "name": "English",
          "company_id": 1,
          "created_at": "2021-09-01T12:31:19.000000Z",
          "updated_at": "2021-09-01T12:31:19.000000Z",
          "pivot": {
            "queue_id": 1,
            "skill_id": 1
          }
        },
        ...
      ]
    }
  ],
  "personal_queue": null
}

Hours of operation

Currently authenticated user

Get the current authenticated user

Authorization required

User must be authenticated and have an active account.

All authorization requests require you to first be authenticated.

GET /api/me

Queues

Get all queues

Authentication: You need to be logged in to access this resource.

Authorization: You must be authorized to access this resource.

GET /api/queues

Parameter	Type	Rules	Default	Description
with	array	Can be any combination of: queries, unansweredQueries, latestQuery, skills, companyUser	-	What related objects to append to the JSON response
scopes	array	Can be any combination of: available, active	-	What scopes to apply to the query

[
  {
    "id": 1,
    "name": "English MacOS Support",
    "company_id": 1,
    "priority_delay": 180,
    "is_active": true
  },
  {
    "id": 2,
    "name": "German MacOS Support",
    "company_id": 1,
    "priority_delay": 180,
    "is_active": true
  },
]

The available scope checks that the queue is active, and that there are active and online users on the queue. The active scope only checks if the queue is active.

Get a single queue

Authentication: You need to be logged in to access this resource.

Authorization: You must be authorized to access this resource.

GET /api/queues/{queue-id}

Parameter	Type	Rules	Default	Description
with	array	Can be any combination of: queries, unansweredQueries, latestQuery, skills, companyUser	-	What related objects to append to the JSON response

Sample response:

{
  "id": 2,
  "name": "German MacOS Support",
  "company_id": 1,
  "priority_delay": 180,
  "is_active": true
}

Create a new queue

Authentication: You need to be logged in to access this resource.

Authorization: You must be authorized to access this resource.

POST /api/queues

Parameter	Type	Rules	Required	Default	Description
name	string	Text	✅	-	The name of the queue
company_id	integer	A valid company ID	✅	-	The ID of the company this queue belongs to
password	string	TODO: password rules	-	-	The password for this queue (see: Concept Overview - password protected queues)
priority_delay	number	A valid integer	-	-	Time delay in seconds for a query to escalate to additional users (see: Concept Overview - queue routing logic)
is_active	boolean	true or false	✅	true	Whether this queue is active or not
skill_ids	array	Array of valid skill IDs	-	-	An array of ID's of skills that the queue requires

Delete a queue

Note: queues with a set company_user_id cannot be deleted. To delete such queues, remove the user from the company.

Queries

Get all queries

Authorization required

User must be authenticated and have rights for the company.

All authorization requests require you to first be authenticated.

GET /api/queries

Parameter	Type	Rules	Default	Description
with	array	Can be any combination of: companyUsers, queues, latestQueue, notes	-	What related objects to append to the JSON response
scopes	array	Can be any combination of: completed, ongoing, company_id, company_user_id	-	What scopes to apply to the query

Create a new query

POST /api/queries

Parameter	Type	Rules	Required	Default	Description
source	string	String with no whitespace	✅	-	A link, phone number, or other reference to where the query is
email	string	A valid email address	✅	-	The email address of the person seeking assistance
is_link	boolean	true or false	✅	true	Whether this query is accessible via a hyperlink or not. E.g http(s) / mailto / tel
name	string	-	✅	-	The name of the person seeking assistance
surname	string	-	-	-	The surname of the person seeking assistance
queue_id	integer	A valid queue ID	✅	-	The ID of the queue this query belongs to

Answer a query

Authorization required

User must be authenticated and have rights for the company, as well as all required skills for the queue (unless the queue is a personal queue that belongs to the authenticated person) Also see: Concept Overview - queue routing logic.

All authorization requests require you to first be authenticated.

TIP

You will additionally get back a 403 forbidden response if the query has already been answered on all the queues it was waiting on.

POST /api/queries/{id}/answer

Mark a query as done

Authorization required

User must be authenticated and have rights for the company.

All authorization requests require you to first be authenticated.

TIP

You will additionally get back a 403 forbidden response if the query was not last answered by you.

POST /api/queries/{id}/mark-as-done

Transfer a query

Authorization required

User must be authenticated and have rights for the company that the queue they are transferring to belongs to.

All authorization requests require you to first be authenticated.

TIP

You will additionally get back a 403 forbidden response if the queue you are transferring to is a personal queue and the user it belongs to is not available.

POST /api/queries/{id}/transfer

Parameter	Type	Rules	Required	Default	Description
queue_id	id	Valid queue ID	✅	-	The ID of the queue you want to transfer to

Query notes

You can add additional notes to each query that are visible to all users responding to a query, regardless of the queue.

Get all query notes

GET /api/query-notes

Query queues

The queues that a given query is on. To get this data, append the queue object when listing queries.

Ratings

Skills

Get all skills

Authentication: You need to be logged in to access this resource.

Authorization: You must be authorized to access this resource.

GET /api/skills

Sample response:

[
  {
    "id": 1,
    "name": "English",
    "company_id": 1
  },
  {
    "id": 2,
    "name": "German",
    "company_id": 1
  },
  {
    "id": 3,
    "name": "MacOS",
    "company_id": 1
  },
  ...
]

Get a single skill

Authentication: You need to be logged in to access this resource.

Authorization: You must be authorized to access this resource.

GET /api/skills/{skill-id}

Sample response:

{
  "id": 2,
  "name": "German",
  "company_id": 1
}

Create a single skill

Authentication: You need to be logged in to access this resource.

Authorization: You must be authorized to access this resource.

POST /api/skills

Parameter	Type	Rules	Required	Default	Description
name	string	Text	✅	-	The name of the skill
company_id	integer	A valid company ID	✅	-	The ID of the company this skill belongs to

Update a company users skills

Authorization required

User must be authenticated and have rights for the company, as well as have the staffing-manager role or the manager role.

All authorization requests require you to first be authenticated.

TIP

This is a synchronous operation, meaning you must pass all the skill_ids that you want the user to have. Existing skill IDs that are not passed will be removed from the user.

PUT /api/company-users/{company-id}/skills

Parameter	Type	Rules	Required	Default	Description
skill_ids	array	-	✅	-	Array of skill ID's to sync

Users

Get a single user

Authentication: You need to be logged in to access this resource.

Authorization: You must be authorized to access this resource.

GET /api/users/{user-id}

Parameter	Type	Rules	Default	Description
with	array	Can be any combination of: companies, skills, queues	-	What related objects to append to the JSON response

Sample response:

{
  "id": 1,
  "name": "Hans",
  "surname": "Schmidt",
  "email": "hans.schmidt@domain.com",
  "avatar_url": "https://image.com/this.jpg",
  "companies": [
    {
        "id": 1,
        "name": "Company 1",
        ...
    }
  ],
  "queues": [
    {
        "id": 1,
        "name": "German MacOS Support",
        "company_id": 1,
        ...
    }
  ],
  "skills": [
    {
        "id": 2,
        "name": "German",
        "company_id": 1
    },
    {
        "id": 3,
        "name": "MacOS Support",
        "company_id": 1
    },
    ...
  ]
}