x-hoppers Smart Notifications

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

Created: October 2024

Permalink:

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 scans 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.

Requirements

WMS 6.08 and higher
PBX on x-hoppers licenses

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
`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` \| `Call` \| `VideoCall`
`event`	Description of the event	string	yes		Example: help needed, theft, dwell_time_exceeded, queue
`broadcastMessage`	Message to announce in the broadcast	string	yes		Example: Help needed at Till Point 3, Theft detected at Canned Food Area Suggested format: `$event at $from area`
`conferenceId`	ID of the target broadcast	string	yes		Conference ID (digits)
`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 can be passed to the data-engine (it’s an additional id for customer’s purposes; request’s main id is generated by 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 --conf_recording --daemon --mode calls presence xhop -e -l 4

The HTTP API proxies requests to the data engine API:

/usr/sbin/data_engine_cli xhop::SmartNotification::${DATA}

where ${DATA} is a base64-encoded JSON payload containing the request parameters, for example:

/usr/sbin/data_engine_cli xhop::SmartNotification::1::eyJmcm9tIjogInNob3AiLCAibm90aWZpY2F0aW9uVHlwZSI6ICJicm9hZGNhc3RNZXNzYWdlIiwgImV2ZW50IjogImhlbHAgbmVlZGVkIiwgImJyb2FkY2FzdE1lc3NhZ2UiOiAiaGVscCBpcyBuZWVkZWQiLCAiY29uZmVyZW5jZUlkIjogIjEifQ==

/usr/sbin/data_engine_cli xhop::SmartNotification::eyJmcm9tIjogInNob3AxIiwgIm5vdGlmaWNhdGlvblR5cGUiOiAiYnJvYWRjYXN0TWVzc2FnZSIsICJldmVudCI6ICJoZWxwIG5lZWRlZCIsICJicm9hZGNhc3RNZXNzYWdlIjogIkhlbHAgaXMgbmVlZGVkIG9uIHRoZSBzZWNvbmQgZmxvb3IiLCAiY29uZmVyZW5jZUlkIjogIjEiLCAicGxheUZyZXF1ZW5jeSI6IDEwLCAiY29uZmlybWF0aW9uVGltZW91dCI6IDMwLCAicXVldWVUaW1lb3V0IjogMzAwLCAicHJpb3JpdHkiOiAwLCAib3JpZ2luIjogIlFSIiwgImN1c3RvbVJpZCI6ICI2OWMwMzM0Ni1mZjY4LTRiZmQtYjM3Zi0yYTZiOGY3YTAyNDkifQ==

To check the status of the current request, use the following command:
```
data_engine_cli xhop::state | jq
```

Possible responses

Below are the possible response types:

{"type": "result", "result": {"requestId": "d7037f0b-23d8-46d5-9909-96867fb7fa56"}}

{"type": "error", "reason": "'conferenceId' is a required property"}

{"type": "error", "reason": "'playFrequency' validation error: 100 is greater than the maximum of 30"}

Configure Dialplan

To be able to receive smart notifications for x-hoppers headsets, proceed with the following steps:

Download the provided procedure
Access WMS 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 a queued request reaches its TTL (Time to Live) without action
join_conference - connects an associate to a broadcast to discuss or respond to the request
playback_finished - Invoked 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
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

Post smart notifications to a group conversation

To configure smart notifications to be posted directly to a group conversation, proceed with the following steps:

Create a dedicated group conversation or use an existing one with all the associates connected to a broadcast
Copy the conversation ID (available in the URL of the conversation)

Add the following data to the /rw2/etc/pbx/x-hoppers.json file:

[
  {
    "audio_conf_id": "2",
    "xbees_channel_id": "f6d17593-98b6-471d-941a-cd03153f"
    "smart_notification_user_extension": 777
  }
]

where

audio_conf_id is the ID of the broadcast channel in x-hoppers where the communication takes place
xbees_channel_id is the ID of the group conversation, where the content is posted
smart_notification_user_extension is the extension number of a user who is designated as the owner of the smart notifications posted to the conversation

Detailed description on how to create conversation can be found in x-hoppers Admin Guide.

x-hoppers smart notifications-Post in a group chat.jpg