This guide explains how to configure x-hoppers smart notification feature.
Created: October 2024
Permalink: https://x-hoppers.atlassian.net/wiki/x/EoCeB
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.
Requirements
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 |
|---|---|---|---|---|---|
| Source of the event (area, department, camera etc.) | string | yes |
| Example: Camera1, Till Point 4, Frozen Food |
| Type of notification desired | string | yes |
| Valid: |
| Description of the event | string | yes |
| Example: help needed, theft, dwell_time_exceeded, queue |
| Message to announce in the broadcast | string | yes |
| Example: Help needed at Till Point 3, Theft detected at Canned Food Area |
| ID of the target broadcast | string | yes |
| Conference ID (digits) |
| Frequency (in seconds) for repeating the request | integer | optional | 10 | Valid range: 5–30 |
| Time (in seconds) to wait for confirmation | integer | optional | 30 | Valid range: 0–600 |
| Time (in seconds) the queued request waits before processing | integer | optional | 60 | Valid range: 5–600 |
| Source of the request | string | optional | NULL | Example: QR, AIVA, Tablet, Task management SW, CallButtons |
| Priority of notification (FIFO by default) | integer | optional | 0 | Valid: positive integers |
| 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 confirmationXHOP_SMART_NOTIFICATION_QUEUE_TIMEOUT: timeout for queued requestsXHOP_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 auto
Configure Dialplan
To configure smart notifications for playback on 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
The imported procedure contains the following called numbers:
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 |
|---|---|
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 transcribed and 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.
