x-hoppers integration with Veesion

This guide explains how to configure x-hoppers integration with Veesion, software that allows to detect thefts in real time. 

Created: January 2023

Updated: June 2023

Permalink: https://wildix.atlassian.net/wiki/x/AQA_Bg

Other documentation: x-hoppers User Guide,  x-hoppers Admin Guide

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.


How to configure Veesion integration

Note: The support starts from WMS Beta 6.02.20221228.1.

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

Note: For PBX authorization, the webhook URL should contain the parameter with PBX token /?token=<simple>.  

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

  1. Add a Dialplan rule named veesion
  2. In the veesion Dialplan, add the following numbers:
    1. *Alerts", with application Conference and the relevant Room Number:


    2. veesion, with the application Play sound, typing text and variables to be played in the conference.

      Example: Attention! Theft detected in ${storeId} on ${cameraId}

      Available variables:

      • storeId
      • startDate
      • endDate
      • cameraIp
      • cameraId
      • groupId
      • videoUrl
      • alertType

How to post Veesion alerts to x-bees conversation

Starting from WMS 6.03.20230630.3, it is possible to configure Veesion alerts to be sent to x-bees conversation (you can refer to x-bees documentation for more information about x-bees). The message that is sent to x-bees includes alert type, date, time, camera IP, ID of the camera and group, as well as the relevant video attachment. 

Note: The feature works only if there is an x-hoppers license available on the PBX.


To configure the functionality:

  1. Add a user in WMS
  2. Create x-bees 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": "f6d17593-98b6-471d-941a-cd03153f",
        "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-bees conversation, copied in step 2, where the content will be posted.
    • user: user, on behalf of whom the content will be posted