x-hoppers Smart Notifications

Owned by Ksenia Babych
Last updated: Nov 22, 2024
4 min read

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

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

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

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

  • reload systemd and restart the service to apply the changes:

    # systemctl daemon-reload # systemctl restart pbx-data-engine

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