Skip to content

Queues

API information

The queue resource is managed by the Queues API.

XPKit Portal

It is recommended queues are created in XPKit Portal, with the management of items in a queue by your applications making direct API requests.

Service URLs

Region URL
AMER https://queues.amer.xpkit.net
APAC https://queues.apac.xpkit.net
China https://queues.china.xpkit.cn
EMEA https://queues.emea.xpkit.net

OpenAPI Specification

Resource name Documentation Download
Queue, QueueItem View Link

Example queue configuration

{
    "name": "Play VR game queue",
    "queue_id": "play-vr-game-queue",
    "experience_id": "developer-conference-2022",
    "rules": [
        {
            "action": "send_notification",
            "action_field": "status",
            "action_value": "call",
            "action_identifier": "you-are-up-next"
        },
        {
            "action": "cancel_item",
            "action_field": "status",
            "action_value": "call",
            "action_identifier": "3600"
        }
    ]
}

Rules

XPKit provides two types of rules that you can set on a queue:

  • send_notification: send a notification, using a campaign_id (action_identifier) when a queueitem's status (action_field) is assigned a particular value (action_value)
  • cancel_item: move a queueitem to the cancel status when its current status (action_field) has been a particular value (action_value) for a certain amount of seconds (action_identifier)

Example queueitem resource

{
    "status": "wait",
    "priority": 1,
    "group": "redteam",
    "instance": "vr_01",
    "notification_sms": "+441234567890",
    "notification_email": "sarah.jones@abc.com",
    "notification_profile": "b0fc813f-c6b5-4334-97d5-153c4fe6053b",
    "notification_data": {
        "first_name": "Sarah",
        "last_name": "Jones"
    }
}

Status

A queueitem can have one of the following status:

  1. wait
  2. call
  3. confirm
  4. ready
  5. play
  6. complete
  7. cancel

Notifications

If a rule is configured to send a notification the following fields are important in a queueitem:

  • notification_sms: if the selected notification campaign is of type SMS, this is required. The phone number should match the phone number against a profile (profile.mobile_number) exactly if an SMS_SENT activity is to be created. Country code is required.
    • notification_profile: as profile.mobile_number is not guaranteed to be unique (email has a unique constraint) a profile resource ID (UUID) can be passed in this field so the SMS_SENT activity is created for the correct profile.
  • notification_email: if the selected notification campaign is of type email, this is required. The email should match an email (profile.email) against a profile exactly if an EMAIL_SENT activity is to be created.
  • notification_data: anything provided here will be passed onto the Notifications API and can then be used in context personalisation tags in email templates (or SMS messages).

Real time queue updates

After your application has added or updated a queueitem the event is broadcast over a websocket so any applications that need to refresh their view of the queue can do so automatically.

Websocket service URL

Region URL
AMER wss://queues-status.amer.xpkit.net/{% account_id %}/{% queue_id %}/{% instance:optional %}
APAC wss://queues-status.apac.xpkit.net/{% account_id %}/{% queue_id %}/{% instance:optional %}
China wss://queues-status.china.xpkit.cn/{% account_id %}/{% queue_id %}/{% instance:optional %}
EMEA wss://queues-status.emea.xpkit.net/{% account_id %}/{% queue_id %}/{% instance:optional %}

If you are unsure what your Account ID (account_id) is you can find it in XPKit Portal.

JavaScript example

const websocket = new WebSocket("wss://queues-status.emea.xpkit.net/f5df5da5-54be-4f75-97b5-d20e7c53c612/play-vr-game-queue");
websocket.onmessage = function (event) {
    let data = JSON.parse(event.data);
    let queue_item = data.resource;
    console.log(`The priority for this queue item is ${queue_item.priority}`)
};

Where event.data will return the updated queueitem in the standard XPKit response format.

Notes on queues and queue items

  • Do not provide a queue_id field in queue CRUD requests. The field will be ignored and auto generated from the provided name field.
  • Queue items can be assigned a priority, a positive integer from 1 to 10. The higher the number the higher the priority. This allows you to push VIP visitors up the queue.
  • A combination of the values of the status and priority fields will affect the order in which items are returned in the queueitem list endpoint.
    • If a status is not provided it will default to wait
    • If a priority is not provided it will default to 1
    • Items that are non-active (where status is complete or cancel) are not returned in the list endpoint unless specifically requested using the status param (?status=all)