Queue Management API

Content

This guide provides information on how to interact with the Queue Management REST API of Bloom Enterprise.

Through HTTP requests, this API allows generating and managing tickets, and requesting tickets lists per status and the overall queuing status.

How to use

HTTP fundamentals

It is required a universal syntax to identify each service in the RESTful API, which is redirected by its URI (Uniform Resource Identifier). All API requests are made through HTTP requests to the URI, referring in the URI the service it must consume. Depending on the service’s action, the request’s header must have the operation which represents the aimed resource’s manipulation.

Operation	Description
DELETE	Responsible for a specific resource.
GET	Responsible for reading a specific resource.
POST	Responsible for transferring the status of a specific resource.
PUT	Responsible for creating or updating a resource set by the URI.

The data output must be specified in the URI, although by omission, the operation’s result is given in JSON format. In case the expected output to be XML format, it must be specified in the address.

The basic URI is:

http://SERVER_IP:HTTP_PORT/restapi/v2/queuemanagement/requested_operation?format=xml

Where:

Item	Value
SERVER_IP	Bloom Enterprise server’s IP address.
HTTP_PORT	HTTP communication port (optional).
requested_operation	Requested system operation.
format=xml	To get a response in XML format (optional).

tip

If HTTP_PORT empty, it will assume the port 80 by default.

All answers are followed by the request’s success status. For instance, the structure of the result of calling a ticket is:

{
     "success" : true,
     "answer" : {
          (...)
     }
}

In case of failure, all messages will be followed by an error code:

{
  "success": false,
  "errno": 2
}

Where:

URI not specified.
Invalid HTTP method.
Invalid operation.
Invalid answer format.
Invalid parameters.
No values found.
The operation cannot be concluded.
No tickets available.
Unknown error.

All error codes above 100, are related to specific operations, and their descriptions will be in the trigger operations.

danger

If the integration you are trying to develop will require pooling Bloom Enterprise’s REST API, you should use WebSockets instead. Please contact Q-Better’s team to know more details.

API Authentication

It is possible to enable/disable bloom API authentication, this way we assure every queue management communication with API is done only by authenticated users and the amount of results shown are only the ones authorised.

To enable/disable API authentication all we need to do is navigate to Settings and enable the option “Enable API authentication” as shown below.

Alt image QM API 1

Once the option is enabled we use the following endpoint to manage the authorizations.

This request allows users to login in order to use the API. The response includes the generated authorization key (JWT) which should be used in all the request headers as “Authorization”.

The Authorization header is a bearer token and it should be used as follow:

Key	Value
Authorization	Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiI4NzkzNjBlOWY(...)

note

The generated authorization key, for security reasons, is valid only for seven days. After this period a new key should be requested.

Item	Value
Requested operation	login
HTTP method	POST
Parameters	user_id (string)ID of the user.

Response structure

{
  "success" : Boolean,
  "user_id" : String,
  "username" : String,
  "authtoken" : String,
}

Tickets Management

Call a specific ticket

This request allows calling a specific ticket. The response includes all information about that ticket.

Item	Value
Requested operation	callticket
HTTP method	POST
Roles Required	acl_qmpad_access qm_qmpad_select_services qm_qmpad_issues_services, Access QM-PAD The user can select services The user can select tickets from the waiting list
Parameters	desk_id (string) ID of the counter.
	user_id (string) ID of the user.
	ticket_id (string) ID of the ticket.

Response structure

{
  "success" : Boolean,
  "answer" : {
    "id" : String,
    "call_date" : String (format: aaaa-mm-dd hh:mm:ss),
    "end_date" : String (format: aaaa-mm-dd hh:mm:ss),
    "state" : String,
    "ticket" : {
      "id" : String,
      "number" : String,
      "date" : String (format: aaaa-mm-dd hh:mm:ss),
      "cancelled" : String,
      "transferred" : String,
      "state" : String,
      "note" : String,
      "lang" : String,
      "custom_field" : String,
      "client_name" : String,
      "flags" : String,
      "app_displayname" : String,
      "app_id" : String,
      "scheduled_to" : String (format: aaaa-mm-dd hh:mm:ss),
      "ticket_service" : {
        "id" : String,
        "name" : String,
        "tag" : String,
      },
      "dst_service" : {
        "id" : String,
        "name" : String,
        "tag" : String,
      },
      "dst_desk" : {
        "id" : String,
        "name" : String,
        "tag" : String,
      },
      "dst_user" : {
        "id" : String,
        "display_name" : String,
        "username" : String,
      },
      "device" : {
        "id" : String,
        "type" : String,
        "name" : String,
      }
    }
  }
}

Call the next ticket

This request allows calling the next ticket. The response includes all information about that ticket.

Item	Value
Requested operation	callnextticket
HTTP method	POST
Roles Required	acl_qmpad_access qm_qmpad_issues_services, Access QM-PAD The user can select services The user can select tickets from the waiting list
Parameters	desk_id (string) ID of the counter.
	user_id (string) ID of the user.
	services (array JSON) ID's of the services.

Response structure

{
  "success": Boolean,
  "answer": {
    "id": String,
    "call_date": String,          // format: "aaaa-mm-dd hh:mm:ss"
    "end_date": String,           // format: "aaaa-mm-dd hh:mm:ss"
    "state": String,
    "ticket": {
      "id": String,
      "number": String,
      "date": String,             // format: "aaaa-mm-dd hh:mm:ss"
      "cancelled": String,
      "transferred": String,
      "state": String,
      "note": String,
      "lang": String,
      "custom_field": String,
      "client_name": String,
      "flags": String,
      "app_displayname": String,
      "app_id": String,
      "scheduled_to": String,     // format: "aaaa-mm-dd hh:mm:ss"

      "ticket_service": {
        "id": String,
        "name": String,
        "tag": String
      },

      "dst_service": {
        "id": String,
        "name": String,
        "tag": String
      },

      "dst_desk": {
        "id": String,
        "name": String,
        "tag": String
      },

      "dst_user": {
        "id": String,
        "display_name": String,
        "username": String
      },

      "device": {
        "id": String,
        "type": String,
        "name": String
      }
    }
  }
}

Recall the ticket

This request allows recalling the ticket.

Item	Value
Requested operation	recall
HTTP method	POST
Roles Required	acl_qmpad_access, Access QM-PAD
Parameters	answer_id (string) ID of the answer .

Response structure

{
  "success" : Boolean
}

tip

answer_id - ID field from the answer object received when calling the createTicket method.

End ticket

This request allows ending the service of the ticket.

Item	Value
Requested operation	endcall
HTTP method	POST
Roles Required	acl_qmpad_access, Access QM-PAD
Parameters	answer_id (string) ID of the answer .

Response structure

{
  "success" : Boolean
}

Pause ticket

This request allows pausing the service of the ticket.

Item	Value
Requested operation	pausecall
HTTP method	POST
Roles Required	acl_qmpad_access Access QM-PAD, qm_qmpad_user_pause_ticket The user can pause tickets
Parameters	answer_id (string) ID of the answer .

Response structure

{
  "success" : Boolean
}

Call a paused ticket

This request allows calling a paused ticket. The response includes all information about that ticket.

Item	Value
Requested operation	callpausedticket
HTTP method	POST
Roles Required	acl_qmpad_access Access QM-PAD
Parameters	desk_id (string) ID of the counter .
	user_id (string) ID of the user .
	ticket_id (string) ID of the ticket .

Response structure

{
  "success": Boolean,
  "answer": {
    "id": String,
    "call_date": String,         // format: "aaaa-mm-dd hh:mm:ss"
    "end_date": String,          // format: "aaaa-mm-dd hh:mm:ss"
    "state": String,
    "ticket": {
      "id": String,
      "number": String,
      "date": String,            // format: "aaaa-mm-dd hh:mm:ss"
      "cancelled": String,
      "transferred": String,
      "state": String,
      "note": String,
      "lang": String,
      "custom_field": String,
      "client_name": String,
      "flags": String,
      "app_displayname": String,
      "app_id": String,
      "scheduled_to": String,    // format: "aaaa-mm-dd hh:mm:ss"

      "ticket_service": {
        "id": String,
        "name": String,
        "tag": String
      },

      "dst_service": {
        "id": String,
        "name": String,
        "tag": String
      },

      "dst_desk": {
        "id": String,
        "name": String,
        "tag": String
      },

      "dst_user": {
        "id": String,
        "display_name": String,
        "username": String
      },

      "device": {
        "id": String,
        "type": String,
        "name": String
      }
    }
  }
}

Cancel the ticket

This request allows cancelling the ticket.

Item	Value
Requested operation	cancelcall
HTTP method	POST
Roles Required	acl_qmpad_access Access QM-PAD
Parameters	answer_id (string) ID of the answer .

Response structure

{
  "success" : Boolean
}

Call a cancelled ticket

This request allows calling a cancelled ticket. The response includes all information about that ticket.

Item	Value
Requested operation	callcancelledticket
HTTP method	POST
Roles Required	acl_qmpad_access Access QM-PAD
Parameters	desk_id (string) ID of the counter .
	user_id (string) ID of the user .
	ticket_id (string) ID of the ticket .

Response structure

{
  "success": Boolean,
  "answer": {
    "id": String,
    "call_date": String,             // format: aaaa-mm-dd hh:mm:ss
    "end_date": String,              // format: aaaa-mm-dd hh:mm:ss
    "state": String,
    "ticket": {
      "id": String,
      "number": String,
      "date": String,               // format: aaaa-mm-dd hh:mm:ss
      "cancelled": String,
      "transferred": String,
      "state": String,
      "note": String,
      "lang": String,
      "custom_field": String,
      "client_name": String,
      "flags": String,
      "app_displayname": String,
      "app_id": String,
      "scheduled_to": String,       // format: aaaa-mm-dd hh:mm:ss
      "ticket_service": {
        "id": String,
        "name": String,
        "tag": String
      },
      "dst_service": {
        "id": String,
        "name": String,
        "tag": String
      },
      "dst_desk": {
        "id": String,
        "name": String,
        "tag": String
      },
      "dst_user": {
        "id": String,
        "display_name": String,
        "username": String
      },
      "device": {
        "id": String,
        "type": String,
        "name": String
      }
    }
  }
}

Transfer the ticket

This request allows transferring the ticket to another service, counter, or user.

Item	Value
Requested operation	transfercall
HTTP method	POST
Roles Required	acl_qmpad_access Access QM-PAD, qm_qmpad_transfer_tickets The user can transfer tickets
Parameters	answer_id (string) ID of the answer .
	dst_type (string) Type of the transfer destination (“service”, “desk”, “user”).
	dst_id (string) ID of the transfer destination
	note (string) Text note associated to the ticket (optional).
	priority (string) Sets the ticket as a priority ticket.
	custom_field (string) Custom text field to add to the transferred ticket (optional).
	desk_id (string) ID of the counter

Response structure

{
  "success" : Boolean
}

Tickets

Generate a ticket

This request allows generating a ticket for a specific service. The response includes all ticket information, and the field ticket_strings which responds with the requested text content for the printed ticket, if a device_id has been specified. These texts are translated according to the language specified in the field lang (by default, if there is no specified language, it will assume the system’s language).

Item	Value
Requested operation	createticket
HTTP method	POST
Roles Required	acl_qmpad_access Access QM-PAD, qm_qmpad_select_services The user can select services, qm_qmpad_issues_services The user can select tickets from the waiting list
Parameters	desk_id (string) ID of the counter (optional).
	user_id (string) ID of the user (optional).
	service_id (string) ID of the service.
	lang (string) ID of the language for the generated ticket (optional).
	custom_field (string) Custom text field associated to the transferred ticket (optional).
	client_name (string) Visitor’s name (optional).
	device_id (string) ID of the device in which the ticket was generated (optional).
	priority (bool) Identifies if the ticket is a priority ticket (optional).
	appointment (string) Identifies if the ticket is an appointment ticket (optional).
	scheduled_to (string) Appointment date in format: aaaa-mm-dd hh:mm:ss (optional).
	from_virtualticket (string) Identifies if the ticket is a virtual ticket (optional).

Response structure

{
  "success": Boolean,
  "ticket": {
    "id": String,
    "number": String,
    "date": String,                      // format: aaaa-mm-dd hh:mm:ss
    "cancelled": String,
    "transferred": String,
    "state": String,
    "note": String,
    "lang": String,
    "custom_field": String,
    "client_name": String,
    "flags": String,
    "app_displayname": String,
    "app_id": String,
    "scheduled_to": String,             // format: aaaa-mm-dd hh:mm:ss
    "ticket_service": {
      "id": String,
      "name": String,
      "tag": String
    },
    "dst_service": {
      "id": String,
      "name": String,
      "tag": String
    },
    "dst_desk": {
      "id": String,
      "name": String,
      "tag": String
    },
    "dst_user": {
      "id": String,
      "display_name": String,
      "username": String
    },
    "device": {
      "id": String,
      "type": String,
      "name": String
    },
    "number_of_waiting_tickets": String,
    "avg_waiting_time": String          // format: hh:mm:ss
  },
  "ticket_strings": {
    "people_waiting": String,
    "waiting_time": String,             // in seconds
    "date_text": String,
    "prioritary_ticket": String,
    "extra_text": String,
    "footer_text": String
  }
}

List of paused tickets

This request allows listing the paused ticket of a specific service.

Item	Value
Requested operation	pausedticketslist
HTTP method	POST
Parameters	desk_id (string) ID of the counter .

Response structure

{
  "success": Boolean,
  "tickets": [
    {
      "id": String,
      "number": String,
      "date": String,              // formato: aaaa-mm-dd hh:mm:ss
      "cancelled": String,
      "transferred": String,
      "state": String,
      "note": String,
      "lang": String,
      "custom_field": String,
      "client_name": String,
      "flags": String,
      "app_displayname": String,
      "app_id": String,
      "scheduled_to": String,      // formato: aaaa-mm-dd hh:mm:ss
      "ticket_service": {
        "id": String,
        "name": String,
        "tag": String
      },
      "dst_service": {
        "id": String,
        "name": String,
        "tag": String
      },
      "dst_desk": {
        "id": String,
        "name": String,
        "tag": String
      },
      "dst_user": {
        "id": String,
        "display_name": String,
        "username": String
      },
      "device": {
        "id": String,
        "type": String,
        "name": String
      }
    },
    ...
  ]
}

List of waiting tickets

This request allows listing the waiting tickets of a specific service.

Item	Value
Requested operation	waitingticketslist
HTTP method	POST
Parameters	service_id (string) ID of the service .

Response structure

{
  "success": Boolean,
  "tickets": [
    {
      "id": String,
      "number": String,
      "date": String,              // format: yyyy-mm-dd hh:mm:ss
      "cancelled": String,
      "transferred": String,
      "state": String,
      "note": String,
      "lang": String,
      "custom_field": String,
      "client_name": String,
      "flags": String,
      "app_displayname": String,
      "app_id": String,
      "scheduled_to": String,      // format: yyyy-mm-dd hh:mm:ss

      "ticket_service": {
        "id": String,
        "name": String,
        "tag": String
      },

      "dst_service": {
        "id": String,
        "name": String,
        "tag": String
      },

      "dst_desk": {
        "id": String,
        "name": String,
        "tag": String
      },

      "dst_user": {
        "id": String,
        "display_name": String,
        "username": String
      },

      "device": {
        "id": String,
        "type": String,
        "name": String
      }
    },
    ...
  ]
}

List of cancelled tickets

This request allows listing the cancelled tickets of a specific service. This list is filtered by the ticket tolerance configured in the system’s backoffice.

Item	Value
Requested operation	cancellededticketslist
HTTP method	POST
Parameters	desk_id (string) ID of the counter .

Response Structure

{
  "success": Boolean,
  "tickets": [
    {
      "id": String,
      "number": String,
      "date": String,               // format: yyyy-mm-dd hh:mm:ss
      "cancelled": String,
      "transferred": String,
      "state": String,
      "note": String,
      "lang": String,
      "custom_field": String,
      "client_name": String,
      "flags": String,
      "app_displayname": String,
      "app_id": String,
      "scheduled_to": String,       // format: yyyy-mm-dd hh:mm:ss

      "ticket_service": {
        "id": String,
        "name": String,
        "tag": String
      },

      "dst_service": {
        "id": String,
        "name": String,
        "tag": String
      },

      "dst_desk": {
        "id": String,
        "name": String,
        "tag": String
      },

      "dst_user": {
        "id": String,
        "display_name": String,
        "username": String
      },

      "device": {
        "id": String,
        "type": String,
        "name": String
      }
    }
    ...
  ]
}

Number of waiting tickets and average waiting time

This request allows getting information on the number of waiting tickets and the average waiting time by service.

Item	Value
Requested operation	waitingticketscount
HTTP method	GET

Response structure

{
  "success" : Boolean,
  "services" : [
    {
      "id" : String,
      "tag" : String,
      "description" : String,
      "number_of_waiting_tickets" : String,
      "open" : Boolean,
      "avg_waiting_time" : String (in seconds),
    },
    (...)
  ]
}

tip

To get the list of services from a specific location, insert the location’s URL in the ID.
For example:
/waitingticketscount/location_id

Content​

How to use​

HTTP fundamentals​

API Authentication​

Login user​

Tickets Management​

Call a specific ticket​

Call the next ticket​

Recall the ticket​

End ticket​

Pause ticket​

Call a paused ticket​

Cancel the ticket​

Call a cancelled ticket​

Transfer the ticket​

Tickets​

Generate a ticket​

List of paused tickets​

List of waiting tickets​

List of cancelled tickets​

Number of waiting tickets and average waiting time​

Content

How to use

HTTP fundamentals

API Authentication

Login user

Tickets Management

Call a specific ticket

Call the next ticket

Recall the ticket

End ticket

Pause ticket

Call a paused ticket

Cancel the ticket

Call a cancelled ticket

Transfer the ticket

Tickets

Generate a ticket

List of paused tickets

List of waiting tickets

List of cancelled tickets

Number of waiting tickets and average waiting time