How to set up x-hoppers integration with Veesion

Introduction

Veesion is software that helps to detect thefts in retail stores in real time, by analysing video feeds and sending real time alerts when suspicious behaviour is detected. x-hoppers integration with Veesion is a great way to make your store more secure.

Requirements

• x-hoppers system on WMS 7.0X and higher

• A broadcast configured in x-hoppers admin -> Broadcasts

Positioning of cameras

Like any AI-based system, the accuracy of algorithm decisions is dependent on the context, like positioning of the cameras. The better the positioning, the more the system is capable of recognizing the shoplifting gestures and thus, the higher the detection rate. Below you can find recommendations for the optimal positioning of the cameras: 

• Cameras should be centered on the aisle:

• Detection range: 1.5 to 12m

The closer a shoplifter is to the camera, the higher detection rate (e.g. within 1.5m the detection rate is 70%, in the range of 12m - about 30%).

• Optimal height: 1.8 to 3.5m

The height of the cameras influence the visibility of what is going on in the store and the detection performance.

What to avoid

Below you can find practices that we recommend to avoid, as long as they can lower the detection rate considerably:

• Too wide field of view: when the camera’s field of view is too wide, there can be too many people present simultaneously, which reduces the detection rate because gestures may be hidden by other people or located far away from the camera (>12m).

• Dead angles: customers cannot be seen between two shelves when cameras focus on blocks of shelves from the side. Avoid placing cameras placed laterally on shelves arranged in blocks and make sure cameras focus on the aisles. 

Other

• DVR / NVR model ideally Hikvision or Dahua

• Configuration for secondary video playback:

  • Resolution: 4CIF or D1

  • FPS: 15 or 12

  • Bitrate: 1024Kbps

Configure Veesion integration

Step 1. Configuration of the webhook

Configuration of the webhook should be performed by administrator on the client side. Webhook should include two parameters: 

• URL of the hook (with PBX as host)

• store_veesion_id

Examples of using Veesion API

• Get token:

curl -v --header "Content-Type: application/json" --request POST --data '{"username":"webhook_user@wildix","password":"test"}' https://api.klaxon.veesion.io/token {"token":"1dcbf200cc455968a66baad40b8238bd5165a8","expires_in":"1702.352942"} 

• Get user info:

curl -v --header "Authorization: Token 1dcbf200cc455968a66baad40b8238bd5165a8" --request GET https://api.klaxon.veesion.io/user-info{"user":"webhook_user@wildix","expires_in":"805.326849"}

• Get stores:

curl -v --header "Authorization: Token 1dcbf200cc455968a66baad40b8238bd5165a8" --request GET https://api.klaxon.veesion.io/stores {"stores":[{"store_veesion_id":"test-store-wildix","store_veesion_name":"test store wildix","store_id":""}]} 

• Set hooks:

curl -v --header "Authorization: Token 1dcbf200cc455968a66baad40b8238bd5165a8" --header "Content-Type: application/json" --request POST --data '{"store_veesion_id":"test-store-wildix","hooks":["https://semen.wildixin.com/api/v1/veesion?token=access_Wq1WDc79z3LL2к6eVlKnaHjuwwEWWERVPg9MiWrWLJhHHspsWZ2"]}' https://api.klaxon.veesion.io/hooks2{"message":"OK"}

Hook payload format:

{"store_veesion_id":"test-store-wildix","store_hook_id":"test-store-wildix@wildix","group_id":"5","store_id":"","start_date":"2022-09-27T17:48:50Z","end_date":"2022-09-27T17:49:57Z","camera_ip":"192.168.0.108","camera_id":"5","video_url":"https:\/\/veesion-alerts-global\/alert.mp4","alert_type":"theft"}

Step 2. PBX configuration

To configure PBX, two parameters need to be added to /rw2/etc/env.custom.ini file:

• VEESION_ALERT_ORIGIN=veesion (used as number in Dialplan - see below)

• VEESION_ALERT_CHANNEL={indicate channel that should receive the alert call}

Example:

VEESION_ALERT_CHANNEL=Local/*Alerts*@veesion

Step 3. Dialplan setup

• Add a Dialplan rule named veesion

• In the veesion Dialplan, add the following called numbers:

  • *Alerts* -> add Broadcast application and select the broadcast

  • veesion -> add Play sound application and insert a TTS message and variables to be played in the broadcast, e.g., Attention! Theft detected in ${storeId} on ${cameraId}

Post Veesion alerts to x-hoppers conversation

It is possible to configure Veesion alerts to be sent to x-hoppers conversation. The message that is sent to x-hoppers includes alert type, date, time, camera IP, ID of the camera and group, as well as the relevant video attachment. 

How to configure 

1. Create Veesion user in WMS

2. Create x-hoppers conversation with the user created in step 1 and copy the conversation ID (available in the URL)

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

[  {    "store_veesion_id": "test-store-wildix",    "name": "Store1",    "audio_conf_id": "2",    "location": "Odesa",    "xbees_channel_id": "9e801f25-30c5-43ab-9bd5-2bd32250",    "veesion_user_extension": "12345"  }]

Where:

• store_veesion_id: ID of the store on the Veesion side

• name: name of the store 

• audio_conf_id: ID of the audio broadcast channel in x-hoppers where the communication takes place

• location: location of the store

• xbees_channel_id: ID of the x-hoppers conversation, copied in step 2, where the content will be posted

• user: user, on behalf of whom the content will be posted

How to modify the alert 

It is possible to edit x-hoppers theft alerts: remove camera ID, IP address and group ID, as well as add a message header.

For this, add the following parameters to the /rw2/etc/pbx/x-hoppers.json file:

a) To remove camera IP, camera ID and group ID:

• "remove_camera_ip": true,

• "remove_camera_id": true,

• "remove_group_id": true,

By default, the values are false and camera IP, ID and group ID are displayed in the theft alert.

b) To add message header:

• "xbees_message_header": "header text"

Where "header text" is your custom text for the message header. By default, theft alerts are sent without a header.