Skip to main content

Kiosks and Lobby Displays

This guide is for kiosk hardware vendors, kiosk software vendors, and agency IT teams. It covers check-in kiosks and lobby displays at a location that runs an eCourtDate queue.

In a queue, a visitor joins a line, gets a ticket number (for example DL-004), and waits. Staff at a station (a counter or desk) call the next ticket from the Agency app. A lobby display shows each call, and the visitor goes to the station.

There are two ways to put a kiosk in a lobby:

ApproachUse it whenWhat the integrator builds
eCourtDate kioskThe device can run a web browser.Nothing. Set up the device and its browser, then pair it. eCourtDate supplies the screens.
Other kiosk softwareThe kiosk already runs its own software, or the visitor flow must be custom.The kiosk screens. The software adds each visitor to a line through the Queue API.

Both approaches use the same lines, services, and stations, and staff work the line the same way. A lobby display is always an eCourtDate display (option 1).

Before You Start​

The agency sets up the queue in the Agency app before any device can join it:

  1. Locations. Each kiosk and display belongs to one location.
  2. Lines (Queue Lines). A line is at one location. It has a Ticket prefix (for example DL) and a ranking strategy.
  3. Services (Queue Services). A service is what a visitor comes for, for example "Pay a fine". Each service belongs to a line. A kiosk lists a service only when walk-ins (or remote joining) are turned on for it.
  4. Stations (Queue Stations). A station serves one or more lines. Its Shown to visitors as name (for example "Counter 7") is the name the display shows and reads aloud.
  5. Portal. A kiosk and a display run on one of the agency's portals. Turn the queue on for that portal (see Step 1).

Set up and test in a staging agency first.

Option 1: eCourtDate Kiosk and Lobby Display​

An eCourtDate kiosk or lobby display is a web page on the agency's portal, opened in the device's browser and paired to the agency once. Nothing is installed on the device, and the device never signs in.

DevicePageWhat it does
Kiosk (a touch screen or tablet)https://{portal address}/kioskVisitors touch to begin, choose a service, and get a ticket number.
Lobby display (a TV or monitor)https://{portal address}/displayShows the tickets being called and the station for each, with an optional chime and spoken call.

The portal address is the portal's ecase.io address (for example https://{portal}.ecase.io) or the agency's own web domain.

Device Requirements​

RequirementDetail
BrowserA current version of Chrome, Edge, or another Chromium-based browser. eCourtDate tests the kiosk and display in Chromium.
HTTPSOpen the portal over https://. The pairing cookie is sent only over HTTPS.
CookiesAllow first-party cookies and keep them. Do not use private or incognito mode, or clear cookies on restart: the device loses its pairing and shows a new code.
Kiosk modeRun the browser in its kiosk or single-app mode so visitors cannot leave the page. The portal page has footer links (Terms, Privacy, and Powered by eCourtDate) that open other pages.
SleepTurn off screen sleep in the operating system. The kiosk asks the browser to keep the screen on, but only after the first touch, and each reset ends that request.
Location accessIf the portal requires the visitor's location (the portal's geolocation setting), every portal page asks for it, the kiosk and display included. Allow location access on the device, or turn the setting off for the portal that runs the kiosk.
FramesDo not show the kiosk or display inside an iframe on another site. The portal allows frames only from the portal and agency domains.

Network. The device must reach these hosts over HTTPS (port 443), and secure WebSockets for Ably:

HostUsed for
The portal addressThe pages, scripts, and styles.
assets.ecourtdate.comThe default logo and icons.
ecdportals.s3-us-gov-east-1.amazonaws.comThe agency's uploaded logo.
*.ably.io, *.ably-realtime.com, *.ably.netLive updates on the lobby display. Without them, the display checks for changes every 15 seconds.

Limits on the portal are per IP address: 120 tickets a minute, and 240 display updates a minute. Many devices behind one public IP address share these limits.

Step 1: Turn On the Queue on the Portal​

In the Agency app, open Portals, open the portal, and open its Queue tab:

SettingDefaultWhat it does
Enable QueueOffOpens the join page, the kiosk, and the lobby display on this portal, and lets devices pair to it. When it is off, these pages do not exist on the portal (they return Page Not Found).
Lines OfferedNone ticked (every line)The lines that visitors on this portal can join. When no line is ticked, visitors see every line.
Send appointment check-ins into the queueOnAn appointment's check-in link joins the line at the appointment's location, in place of the plain check-in form.
Show a "Join the line" linkOnAdds Join the line to the portal's menu, so visitors can join from their own phones.

Save the portal. A change can take up to one minute to reach the portal pages.

Step 2: Create a Kiosk Profile​

A kiosk profile sets what a kiosk offers. In the Agency app, open Queue Kiosks and create a profile with a Name and a Location. Then set:

SettingDefaultWhat it does
Services offeredNone ticked (every service)The services the kiosk lists. When no service is ticked, the kiosk lists every service on the location's lines.
Reset after (seconds idle)60Seconds without a touch before the kiosk warns that it will reset. From 15 to 600.
Allow joining without a phone or emailOnWhen it is off, the visitor must give a mobile number or an email address to get a ticket.
Offer a printed ticketOffShows a Print button on the ticket screen. See Printing.
LanguagesEnglishThe languages the visitor can choose. The kiosk shows language buttons when more than one is set.
WelcomeThe portal nameThe first text on the screen, for example "Welcome. Touch to begin." One entry per language, up to 120 characters.

A kiosk paired without a profile uses the defaults: the portal name as the welcome, English only, a 60-second reset, no print button, every service, and no phone or email needed.

Step 3: Create a Display Profile​

A display profile sets what a lobby display shows. In the Agency app, open Queue Displays and create a profile with a Name and a Location. Then set:

SettingDefaultWhat it does
LayoutListList shows one call per row. Grid shows the calls in columns, for wide screens.
Calls kept on screen6How many calls the display shows. From 1 to 20.
Play a chime when someone is calledOnPlays a short tone for each new call.
Read the call aloudOffReads each new call aloud through the browser's speech voice, for example "DL-004. Please proceed to Counter 7."
Lines shownNone ticked (every line)The lines whose calls the display shows. When no line is ticked, it shows every line at the location.
ThemeLightLight or Dark. Light keeps the portal's own colors, unless the portal uses the dark theme. Dark shows the display in the dark theme.
Show the visitor's initials next to the ticketOffShows up to three initials beside each ticket, for example DL-004 JQV. The display never shows a name.
AnnouncementBlankA line of text under the calls, for example "Please have your ID ready." One entry per language, up to 200 characters.

A display paired without a profile uses the defaults, but with the chime off.

Step 4: Pair Each Device​

Pairing connects one browser to the agency, as a kiosk or as a display, at one location.

  1. On the device, open https://{portal address}/kiosk (for a kiosk) or https://{portal address}/display (for a display).
  2. The device shows Pair this device and a six-digit code. The code is good for 15 minutes.
  3. In the Agency app, open Queue Devices.
  4. Under Pair a device, type the code in Code on the device.
  5. In What it is, choose Kiosk or Lobby display.
  6. In Where it is, choose the device's location.
  7. In Profile, choose a profile for that location, or Default.
  8. Optional: type a Name, for example "Lobby screen by the elevators".
  9. Select Pair.

Within a few seconds, the device opens the kiosk or the display. It stays paired for one year, until it is revoked, or until its cookies are cleared.

A device pairs to one portal and works only on that portal's address. The device's location, not the profile's location, decides which lines it shows. Each time the pairing page loads, it shows a new code, so pair with the code that is on the screen now.

What a Visitor Sees on the Kiosk​

  1. Welcome. The portal logo, the welcome text, a Touch to begin button, and the language buttons (for example EN and ES).
  2. What do you need? One button per service. A service whose line is paused, closed, or not taking new visitors shows "This line is not taking new visitors right now" and cannot be chosen.
  3. Please have these ready. Shown only when the service lists requirements.
  4. A few details. The visitor's name (optional), the service's own questions, a mobile number (for text updates), and an email address. Both are optional, unless the profile does not allow joining without a phone or email: then the screen says "Please enter your phone or email." and gives no ticket without one. A service that allows remote joining also asks whether the visitor is here now.
  5. Your ticket. The ticket number and "Keep this number. We will call it."

When the visitor gives a mobile number or email, eCourtDate sends the agency's auto message for the queue_joined trigger, if the agency has one. The message can include the link to the visitor's own status page. Later messages use the queue_approaching and queue_called triggers. The kiosk itself does not show or print a link.

Reset. After the Reset after time without a touch, the kiosk shows "This screen will reset in 20 seconds" with a Continue button. Without a touch in those 20 seconds, the page reloads and clears everything the visitor entered. The ticket screen resets 20 seconds after the last touch. Each reset returns the kiosk to the agency's default language.

Languages. Each language button reloads the kiosk in that language. The ticket and the visitor's later messages use the language on screen. The kiosk screens are translated into more than 50 languages. A language with no translation shows in English.

Appointments. The kiosk has no appointment check-in. A visitor with an appointment who uses the kiosk joins as a walk-in. Visitors with an appointment check in from the check-in link in their reminder (when Send appointment check-ins into the queue is on), or at a staff desk.

Printing​

When Offer a printed ticket is on, the ticket screen has a Print button. The printout has the ticket alone: "Your ticket", the ticket number, and "Keep this number. We will call it." The portal's logo, menus, and footer are not printed.

The button opens the browser's print dialog, so a kiosk that prints without a dialog needs a browser set to print silently to its default printer (for example, Chrome started with --kiosk --kiosk-printing). The ticket fills the width of the paper, so it prints on a receipt printer (for example 80 mm) and on a letter-size printer.

Test the printed ticket on the kiosk's own printer before go-live. Check the margins and that the ticket number prints clearly.

What the Lobby Display Shows​

  • The portal logo and name, a clock, and the number of visitors waiting on the lines shown.
  • Now serving: one row per ticket that is called or being served, newest first, as the ticket and the station's Shown to visitors as name. A display never shows a visitor's name.
  • The announcement, under the calls.

A new call is highlighted and, when set in the profile, chimes and is read aloud. The display gets each call through Ably as it happens. While Ably is not connected, it checks for changes every 15 seconds.

Browsers often block sound until someone touches the page. After the display opens, touch or click it once. The touch also asks the browser for full screen and to keep the screen on.

When the display cannot reach eCourtDate for 90 seconds, it shows "Connection lost. Showing the last known state." and keeps the last calls on screen.

The display opens in the agency's default language. To show it in another language, open it as https://{portal address}/display?lang={code} after it is paired, for example ?lang=es.

Manage Paired Devices​

Queue Devices lists each device with its Type, Location, Status (Paired, Waiting for its code, or Revoked), and Last seen time.

  • Rename, move, or change the profile. Open the device and change Name, Location, or Profile. A change of location sets the profile back to Default. The type cannot change: revoke the device and pair it again.
  • Revoke. Select Revoke to disconnect a device, for example a lost tablet. A revoked kiosk gives no more tickets: the next visitor who tries gets the pairing screen with a new code. A revoked lobby display shows a new pairing code at its next update, within about an hour at most. Reload a revoked device to disconnect it at once.
  • Apply profile changes. A kiosk uses a changed profile after its next reset. A lobby display uses a changed profile after it is reloaded.

Option 2: Other Kiosk Software Through the API​

Kiosk software that has its own screens adds visitors to a line through the Queue API. Staff call the tickets in the Agency app, and an eCourtDate lobby display shows the calls.

Step 1: Get API Credentials​

A Super Admin of the agency creates an API client in the Console under APIs, with the region and the agency, and gives the integrator its Client ID and Client Secret. The steps are in Build a Case Management System Integration. Use the credentials to get a Bearer token (see Authentication).

Keep the credentials on the kiosk software's server, not on the kiosk device: an API client can change every record of its agencies. Put the server's public IP addresses in the API client's Allowed IPs. The API accepts requests only from IP addresses in the United States.

Step 2: Find the Lines and Services​

Get the UUIDs of the location's lines and services, and store them in the kiosk software's configuration:

curl "$BASE_URL/v1/queue_lines?location={location_uuid}" \
  -H "Authorization: Bearer $TOKEN"

curl "$BASE_URL/v1/queue_services?line={line_uuid}" \
  -H "Authorization: Bearer $TOKEN"

Before the kiosk shows a line, read its status. Offer the line only when both status and intake are open:

curl "$BASE_URL/v1/queue/lines/{line_uuid}/status" \
  -H "Authorization: Bearer $TOKEN"

Step 3: Add Each Visitor​

Send one request per visitor, with source set to kiosk and a new UUID in the Idempotency-Key header:

curl -X POST "$BASE_URL/v1/queue/visits" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0f8b2d4e-6a1c-4b3e-9d7f-2c5a8e1b4f60" \
  -d '{
    "line": "{line_uuid}",
    "service": "{service_uuid}",
    "source": "kiosk",
    "name": "Jane Doe",
    "phone": "+15551234567",
    "language": "es"
  }'
  • Show or print the ticket from the response, for example DL-004.
  • Retry with the same key. When the network fails, send the request again with the same Idempotency-Key. The retry returns the first visit and adds no second ticket.
  • Give the status page to the visitor only. The response's url is the token of the visitor's status page, https://{portal address}/v/{url}. Print it as a QR code on the ticket, or leave it out. Anyone with the token can see and leave the visit.
  • Handle a closed line. A 423 response means the line is paused, closed, not taking new visitors, or full. Show a plain message, for example "This line is not open. Please see the front desk."
  • Send the visitor's language. Messages to the visitor use language.
  • Appointments. For a visitor with an appointment, send "source": "appointment", the appointment's event UUID, and its appointment_at time in UTC. On a line that ranks appointments, an early arrival can get a 422 that gives the time to come back.

Step 4: Follow or Cancel a Visit​

  • GET /v1/queue/visits/{uuid} returns the visit's queue_state (queued, called, serving, completed, and others) and its estimated call time.
  • POST /v1/queue/visits/{uuid}/cancel removes a visitor who leaves the line at the kiosk.

The kiosk software does not call visitors, start service, or complete visits. Staff do that in the Agency app.

Test, Then Go Live​

In the staging agency:

  1. Pair one kiosk and one lobby display at a test location, or add a test visit through the API.
  2. Join the line from the kiosk. Check that the ticket number has the line's prefix.
  3. In the Agency app, sign in to a station and call the ticket. Check that the display shows the ticket and the station name, and plays the chime.
  4. Give a test mobile number, and check the queue_joined and queue_called messages.
  5. Leave the kiosk idle. Check the reset warning and the reset.
  6. Print a ticket, when printing is on. Check that the ticket prints alone.
  7. Restart the device. Check that it opens paired, without a new code.
  8. Pause the line in the Agency app. Check that the kiosk does not offer it.

To go live, set up the production agency's lines, services, stations, and profiles, then pair the production devices on the production portal.

Troubleshooting​

The kiosk or display page shows Page Not Found. Enable Queue is off on the portal's Queue tab, or the device opened another portal's address. A change to the setting takes up to one minute.

The device shows a new pairing code after a restart. The browser did not keep its cookies, or runs in private mode. Change the browser settings so cookies are kept, then pair again. Revoke the old device entry in Queue Devices.

Staff see "No device is showing that code". The code is more than 15 minutes old, was typed wrong, or was paired already. Reload the device for a new code.

The kiosk shows no services. No active line is at the device's location, the portal's Lines Offered leaves the line out, the profile's Services offered are on another location's lines, or no service has walk-ins turned on.

A service shows "This line is not taking new visitors right now". Staff paused, closed, or stopped new joins on the line, or the line has the most visitors it allows. Pausing calling also stops joining.

The kiosk shows "The line is unavailable right now. Please try again." eCourtDate could not record the ticket, or the queue was turned off for the portal. Try again. If it continues, open a support ticket.

The display shows "Connection lost". The device cannot reach eCourtDate. Check the network and the hosts under Device Requirements. A display that was revoked, or whose portal's queue was turned off, does not show this: it reloads, and shows a pairing code or Page Not Found.

The display does not chime. The device is paired with Default (no profile), the profile's chime is off, or the browser blocks sound. Touch the display once after it opens.

A revoked kiosk still shows the welcome screen. It gives no ticket. The next visitor who tries to get one sees the pairing screen. Reload the kiosk to show the pairing screen at once.

The kiosk asks for a phone or email. The kiosk's profile has Allow joining without a phone or email off. Turn it on in Queue Kiosks to let visitors join without one.