x-hoppers Smart Notifications

This guide explains how to configure x-hoppers smart notifications feature.

Created: October 2024

Updated: March 2025

Permalink: https://x-hoppers.atlassian.net/wiki/x/EoCeB

1 Introduction
2 Requirements
3 Setup
- 3.1 Make an HTTP request
- 3.2 Configure Dialplan

Introduction

The smart notifications feature in x-hoppers enables instant alerts to be broadcasted to store associates when specific events are triggered, such as an assistance requests from till points, QR code-based smart call points or security alerts, etc. This functionality integrates with various devices, including call buttons, cameras, POS systems, through a dedicated Smart Notifications API.

Requests are sorted into multiple queues, with a separate queue for each broadcast. When an event is triggered, store associates receive audio notifications directly on their headsets, as well as text notifications via a mobile or web app. Once an associate accepts a notification by double pressing the Push-to-talk button, the system informs everyone in the broadcast that the request is being handled by a specific associate.

It is also possible to send private notifications to specific store associates. Private notifications are played after the current public ones finish. Meanwhile, public notifications continue broadcasting while the user listens to their private messages.

Requirements

x-hoppers system on WMS 7.0X and higher
A broadcast configured in x-hoppers admin -> Broadcasts

Setup

Make an HTTP request

To initiate a smart notification HTTP request, use the parameters described below. Full details on the parameters can be found in the API documentation or at your PBX https://{subdomain}.wildixin.com/api/v1/doc/#tag/Smart-Notifications/operation/addSmartNotification.

Parameter	Description	Type	Required	Default	Examples / Valid values

Parameter	Description	Type	Required	Default	Examples / Valid values
`from`	Source of the event (area, department, camera etc.)	string	yes		Example: Camera1, Till Point 4, Frozen Food
`notificationType`	Type of notification desired	string	yes		Valid: `BroadcastMessage` \| `PrivateMessage` \| `Call` \| `VideoCall`
`event`	Description of the event	string	yes		Example: help needed, theft, dwell_time_exceeded, queue
`broadcastMessage`	Message to announce in the broadcast or as a private message	string	yes		Example: Help needed at Till Point 3, Theft detected at Canned Food Area Suggested format: `$event at $from area`
`broadcastId`	ID of the target broadcast	string	yes		Broadcast ID. Copy it from the broadcast URL in x-hoppers admin -> Broadcasts -> click Edit, see the picture below:
`extension`	User extension number to get private messages	string	yes		Example: 100, 2503, 5784
`playFrequency`	Frequency (in seconds) for repeating the request	integer	optional	10	Valid range: 5–30
`confirmationTimeout`	Time (in seconds) to wait for confirmation	integer	optional	30	Valid range: 0–600 0 = no confirmation required
`queueTimeout`	Time (in seconds) the queued request waits before processing	integer	optional	60	Valid range: 5–600
`origin`	Source of the request	string	optional	NULL	Example: QR, AIVA, Tablet, Task management SW, CallButtons
`priority`	Priority of notification (FIFO by default)	integer	optional	0	Valid: positive integers
`customRid`	Custom request ID passed to the data engine	string	optional		Example: UUID

Default settings for timeouts, TTL and repeat frequency can be customized with the following environment variables added to /etc/systemd/system/pbx-data-engine.service.d/override.conf file:

XHOP_SMART_NOTIFICATION_CONFIRMATION_TIMEOUT: timeout period for a confirmation
XHOP_SMART_NOTIFICATION_QUEUE_TIMEOUT: timeout for queued requests
XHOP_SMART_NOTIFICATION_PLAY_FREQUENCY: frequency for repeating the notification playback
[Service] Environment='XHOP_SMART_NOTIFICATION_CONFIRMATION_TIMEOUT=65' Environment='XHOP_SMART_QUEUE_TIMEOUT=65' Environment='XHOP_SMART_PLAY_FREQUENCYT=65' ExecStart= ExecStart=/usr/sbin/pbx_data_engine.py --daemon

Configure Dialplan

To configure smart notifications for playback on x-hoppers headsets, proceed with the following steps:

Download the provided procedure
Access x-hoppers admin and navigate to Dialplan menu, Dialplan rules tab
Click Import, select the procedure and click Apply to finish

x-hoppers smart notifications_Import Dilaplan.jpg

The imported procedure contains the following called numbers:

x-hoppers smart notifications_Dilaplan.png

announce - plays an initial or repeated notification to available store associates
confirmed - triggered when an associate accepts a request
expired - called when TTL (Time to live) of a queued request expires
join_conference - connects to a broadcast to announce a request
playback_finished - triggered after the announcement playback is complete. This handler marks the playback as finished and is used to finalize the process for the current notification
timedout - activated when a request times out without an associate’s response

You can customize confirmed, expired and timedout numbers by modifying the confirmation or timeout message, setting an external API etc. To further customize the notification process, use the following channel variables:

Variable	Description

Variable	Description
conf_id	Broadcast ID associated with the request
message	Base64-encoded message to be announced in a broadcast
request_id	Unique identifier (UUID4 format) for each request
extensions	Extension of the associate who accepts the request
name	LDAP name of the associate who accepts the request
received	Timestamp of when the request is received
started	Timestamp of when the request starts processing
finished	Timestamp of when the request is confirmed, timed out or expired
from	Base64-encoded "from" parameter of the request origin
notification_type	Base64-encoded type of notification for the request
event	Base64-encoded event type associated with the request
origin	Base64-encoded origin data of the request
custom_rid	Custom ID parameter from the request

x-hoppers Documentation