Versions Compared

Old Version 1

changes.mady.by.user Ksenia Babych

Saved on

compared with

New Version Current

changes.mady.by.user Ksenia Babych

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Info

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

Created: October 2024

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

Table of Contents
minLevel1
maxLevel6
outlinefalse
stylenone
typelist
printabletrue

...

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

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.

...

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

Tip

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

    Code Block
    [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:

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

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

Code Block
/usr/sbin/data_engine_cli xhop::SmartNotification::1::eyJmcm9tIjogInNob3AiLCAibm90aWZpY2F0aW9uVHlwZSI6ICJicm9hZGNhc3RNZXNzYWdlIiwgImV2ZW50IjogImhlbHAgbmVlZGVkIiwgImJyb2FkY2FzdE1lc3NhZ2UiOiAiaGVscCBpcyBuZWVkZWQiLCAiY29uZmVyZW5jZUlkIjogIjEifQ==
Code Block
/usr/sbin/data_engine_cli xhop::SmartNotification::eyJmcm9tIjogInNob3AxIiwgIm5vdGlmaWNhdGlvblR5cGUiOiAiYnJvYWRjYXN0TWVzc2FnZSIsICJldmVudCI6ICJoZWxwIG5lZWRlZCIsICJicm9hZGNhc3RNZXNzYWdlIjogIkhlbHAgaXMgbmVlZGVkIG9uIHRoZSBzZWNvbmQgZmxvb3IiLCAiY29uZmVyZW5jZUlkIjogIjEiLCAicGxheUZyZXF1ZW5jeSI6IDEwLCAiY29uZmlybWF0aW9uVGltZW91dCI6IDMwLCAicXVldWVUaW1lb3V0IjogMzAwLCAicHJpb3JpdHkiOiAwLCAib3JpZ2luIjogIlFSIiwgImN1c3RvbVJpZCI6ICI2OWMwMzM0Ni1mZjY4LTRiZmQtYjM3Zi0yYTZiOGY3YTAyNDkifQ==

  • To check the status of the current request, use the following command:

    Code Block
    data_engine_cli xhop::state | jq

Possible responses

Below are the possible response types:

Code Block
{"type": "result", "result": {"requestId": "d7037f0b-23d8-46d5-9909-96867fb7fa56"}}
Code Block
{"type": "error", "reason": "'conferenceId' is a required property"}
Code Block
{"type": "error", "reason": "'playFrequency' validation error: 100 is greater than the maximum of 30"}

Configure Dialplan

...

  • auto

Configure Dialplan

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

...

  • 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 actionlive) of a queued request expires

  • join_conference - connects an associate to a broadcast to discuss or respond to the announce a request

  • playback_finished - Invoked 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

...

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:

    Code Block
    [
  {
    "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:

    Code Block
    # systemctl daemon-reload
# systemctl restart pbx-data-engine
Panel
panelIconId1f4d7
panelIcon:green_book:
panelIconText📗
bgColor#E3FCEF

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

...