Trigger Camera Audio Playback via REST API with Custom Sound File in Nx Witness

Answered

May 09, 2025 07:52

I am able to configure camera actions to play sound on event triggers via the Nx Witness GUI, but I need to achieve the same functionality using the REST API. Specifically, I want to trigger audio playback from my code with different sound files that are already available in the system.

I am looking for the correct Nx Witness REST API endpoint and request format to:

Send a command that plays a specific sound file stored on the server or camera.
Dynamically select different sound files based on event triggers.

Has anyone successfully implemented this, or is there a documented API for managing sound playback via REST? Any guidance or examples would be greatly appreciated.

Thanks in advance!

Comments

20 comments

Norman

Network Optix team

May 09, 2025 08:13 Edited
Hi Subramanian,
This is pretty easy to achieve, create the desired rules, one for each specific sound, each with a unique specific trigger name like so:
And trigger the rule with a Generic Event like so:
```
POST https://192.168.178.97:7001/api/createEvent
```
Body:
```
{
    "source": "Specific Trigger"
}
```
This way, you can trigger each sound for each specific situation.
0
Subramanian

May 09, 2025 10:16 Edited
is This correct
0
Norman

Network Optix team

May 09, 2025 12:51
Hi Subramanian,

You should make it simpler, and remove all parameter and values, you don't use.

If you want Source, Caption and Description all being Bell, the following Body should be used:
```
{
    "source": "Bell",
    "caption": "Bell",
    "description": "Bell"
}
```
Personally, I would just use one parameter, for example, just source, as shown below.
Of course, in such case, also remove Bell as the trigger word for caption and description.
0
Subramanian

May 12, 2025 08:04
is it possible to create generic event with out using user involvement in configuring the NX like setting the event in UI . is there any api for that
0
Norman

Network Optix team

May 12, 2025 13:55
Hi Subramanian,
Sure, you can use POST /ec2/saveEventRule to save a rule with the desired body.
I find it most easy to first setup a desired rule by hand, and then do a GET /ec2/getEventRules request, to obtain to applicable formatting, and use that in the aforementioned POST request.
Kind regards.
0
Subramanian

May 13, 2025 06:21
if i have to use this what should i give as a input for bell like previous mesages
0
Norman

Network Optix team

May 13, 2025 08:06
Hi Subramanian,
I'm happy to support you throughout the process, but you'll gain a lot more by trying it yourself.
Here’s what I recommend:
1. Create the desired rule using the GUI.
2. Use a GET request to retrieve the rule format.
3. Apply the desired changes to the rule using a POST request to add it to the VMS.
If you run into any issues or get stuck at any step, just let me know—I’m here to help!
Best regards.
0
Subramanian

May 15, 2025 10:08
I retrieved the details from getEventRules and attempted to use them, but I encountered an error during deserialization. Thanks to your guidance, I now understand how to call saveEvent.
Could you review the JSON structure and let me know if anything is incorrect or missing? I'm still facing a deserialization error and want to ensure the format aligns with the expected schema.
{
"id":"d4ca62ea-0bbc-4721-8e0b-830c8f8b0620",
"eventType":"undefinedEvent",
"eventResourceIds":[

],
"eventCondition":{
"caption":"Bell",
"description":"Bell",
"eventTimestampUsec":"0",
"eventType":"undefinedEvent",
"metadata":{
"allUsers":false,
"level":""
},
"omitDbLogging":false,
"progress":0,
"reasonCode":"none",
"resourceName":"Bell"
},
"eventState":"Undefined",
"actionType":"playSoundOnceAction",
"actionResourceIds":[
"{072cb529-ce4d-8935-91a1-7e83e1162320}"
],
"actionParams":{
"additionalResources":[
"{00000000-0000-0000-0000-100000000000}",
"{00000000-0000-0000-0000-100000000001}"
],
"allUsers":false,
"authType":"authBasicAndDigest",
"durationMs":5000,
"forced":true,
"fps":10,
"needConfirmation":false,
"playToClient":true,
"recordAfter":0,
"recordBeforeMs":1000,
"streamQuality":"highest",
"url":"syren1.mp3",
"useSource":true
},
"aggregationPeriod":10,
"disabled":false,
"comment":"",
"schedule":"",
"system":false,
"EventState":"Undefined"
}

The response indicates:
{
"error": "2",
"errorId": "invalidParameter",
"errorString": "Can't deserialize input Json data to destination object."
}
0

Norman

Network Optix team

May 15, 2025 12:45 Edited

Hi Subramanian,

Not quite, although JSON formatting is valid, I'm not sure how you obtained it, since the formatting differs from what I get.

So, let me iterate how to do it.

First, GET /ec2/getEventRules. This will provide a list of all rules in the system.
I just copy them all, and paste them in my text editor, and search for my word I used in Comment, this way it is easy to find the object you can modify. In this case:

{
    "actionParams": "{\"additionalResources\":[\"{20c805c5-42a6-676f-2527-482bcbf3a514}\"],\"allUsers\":false,\"authType\":\"authBasicAndDigest\",\"durationMs\":5000,\"forced\":true,\"fps\":10,\"needConfirmation\":false,\"playToClient\":true,\"recordAfter\":0,\"recordBeforeMs\":1000,\"streamQuality\":\"highest\",\"url\":\"doorbell.mp3\",\"useSource\":false}",
    "actionResourceIds": [],
    "actionType": "playSoundOnceAction",
    "aggregationPeriod": 0,
    "comment": "doorbell",
    "disabled": false,
    "eventCondition": "{\"eventTimestampUsec\":\"0\",\"eventType\":\"undefinedEvent\",\"metadata\":{\"allUsers\":false,\"level\":\"\"},\"omitDbLogging\":false,\"progress\":0,\"reasonCode\":\"none\",\"resourceName\":\"Bell\"}",
    "eventResourceIds": [],
    "eventState": "Undefined",
    "eventType": "userDefinedEvent",
    "id": "{9f4b1e0c-0e0c-4f8a-9d58-2c423d0d1fc6}",
    "schedule": "",
    "system": false
}

In this sample, I change the following values:

\"url\":\"doorbell.mp3\" to \"url\":\"syren1.mp3\"
"comment": "doorbell", to "comment": "syren",
"resourceName\":\"Bell\" to "resourceName\":\"Syren\"

But the most important of all, I change the ID, since the ID has to be unique.

"id": "{9f4b1e0c-0e0c-4f8a-9d58-2c423d0d1fc6}",

This format is called UUID v4, and consist of 8-4-4-4-12 characters. You can build a script to do it automatically, but you also can generate one online via UUID generator.

So, for example:

So, like this:

"id": "{876b9acf-f61d-48cd-8c72-bd6629eda3bc}",

So the new body you send to the system with POST /ec2/saveEventRule will be:

{
    "actionParams": "{\"additionalResources\":[\"{20c805c5-42a6-676f-2527-482bcbf3a514}\"],\"allUsers\":false,\"authType\":\"authBasicAndDigest\",\"durationMs\":5000,\"forced\":true,\"fps\":10,\"needConfirmation\":false,\"playToClient\":true,\"recordAfter\":0,\"recordBeforeMs\":1000,\"streamQuality\":\"highest\",\"url\":\"syren1.mp3\",\"useSource\":false}",
    "actionResourceIds": [],
    "actionType": "playSoundOnceAction",
    "aggregationPeriod": 0,
    "comment": "syren",
    "disabled": false,
    "eventCondition": "{\"eventTimestampUsec\":\"0\",\"eventType\":\"undefinedEvent\",\"metadata\":{\"allUsers\":false,\"level\":\"\"},\"omitDbLogging\":false,\"progress\":0,\"reasonCode\":\"none\",\"resourceName\":\"Syren\"}",
    "eventResourceIds": [],
    "eventState": "Undefined",
    "eventType": "userDefinedEvent",
    "id": "{876b9acf-f61d-48cd-8c72-bd6629eda3bc}",
    "schedule": "",
    "system": false
}

And that results in the expected HTTP 200 OK response:

And the actual rule in the VMS:

Subramanian

May 15, 2025 14:13

Thanks for all the explanations! However, there's still some clarification needed."

{
 "actionParams": "{\"additionalResources\":[\"{20c805c5-42a6-676f-2527-482bcbf3a514}\"],\"allUsers\":false,\"authType\":\"authBasicAndDigest\",\"durationMs\":5000,\"forced\":true,\"fps\":10,\"needConfirmation\":false,\"playToClient\":true,\"recordAfter\":0,\"recordBeforeMs\":1000,\"streamQuality\":\"highest\",\"url\":\"syren1.mp3\",\"useSource\":false}",
 "actionResourceIds": [],
 "actionType": "playSoundOnceAction",
 "aggregationPeriod": 0,
 "comment": "syren",
 "disabled": false,
 "eventCondition": "{\"eventTimestampUsec\":\"0\",\"eventType\":\"undefinedEvent\",\"metadata\":{\"allUsers\":false,\"level\":\"\"},\"omitDbLogging\":false,\"progress\":0,\"reasonCode\":\"none\",\"resourceName\":\"Syren\"}",
 "eventResourceIds": [],
 "eventState": "Undefined",
 "eventType": "userDefinedEvent",
 "id": "{0d0c04fe-680c-46a2-a646-80efd7e3bf44}",
 "schedule": "",
 "system": false
}

Subramanian

May 16, 2025 06:03

my get call output from /ec2/getEventRules

 {
   "actionParams": "{\"additionalResources\":[\"{00000000-0000-0000-0000-100000000000}\",\"{00000000-0000-0000-0000-100000000001}\"],\"allUsers\":false,\"authType\":\"authBasicAndDigest\",\"durationMs\":5000,\"forced\":true,\"fps\":10,\"needConfirmation\":false,\"playToClient\":true,\"recordAfter\":0,\"recordBeforeMs\":1000,\"streamQuality\":\"highest\",\"url\":\"syren1.mp3\",\"useSource\":true}",
   "actionResourceIds": [
     "{072cb529-ce4d-8935-91a1-7e83e1162320}"
   ],
   "actionType": "playSoundOnceAction",
   "aggregationPeriod": 60,
   "comment": "",
   "disabled": false,
   "eventCondition": "{\"caption\":\"Bell\",\"description\":\"Bell\",\"eventTimestampUsec\":\"0\",\"eventType\":\"undefinedEvent\",\"metadata\":{\"allUsers\":false,\"level\":\"\"},\"omitDbLogging\":false,\"progress\":0,\"reasonCode\":\"none\",\"resourceName\":\"Bell\"}",
   "eventResourceIds": [],
   "eventState": "Undefined",
   "eventType": "userDefinedEvent",
   "id": "{d4ca62ea-0bbc-4721-8e0b-830c8f8b0620}",
   "schedule": "",
   "system": false
 },

Norman

Network Optix team

May 16, 2025 12:58 Edited
Hi Subramanian,
I tried the body of your output with success:
And also the body of the previous message, the one you wanted to add to the system, and with success as well:
Please, before you use the body, validate it with, for example, JSONLint. Small errors will be discovered, like I forgot to copy the closing bracket (}) initially, which resulted in the same error as you got.

For example, in the screenshot, I don't see these lines:
```
 "eventType": "userDefinedEvent",
 "id": "{0d0c04fe-680c-46a2-a646-80efd7e3bf44}",
 "schedule": "",
 "system": false
```
While they are part of the body you shared in plain text. These are required, since they contain the new ID.
As a final note, we generally recommend using an API platform like Postman. The free version offers plenty of flexibility and functionality. While our built-in “Try it out” feature is available, it can occasionally cause text formatting issues that may lead to unexpected behavior.
0

Subramanian

May 19, 2025 06:57

I've been trying to authenticate using Postman following the instructions provided in this post, but I'm still running into a 403 Forbidden error despite setting the vms-token as a Bearer token in the Authorization header.
Here are my setup details:
- OS: Windows 10 Pro
- Wisenet WAVE Client version: 5.1.3.38363 (e4d0848daafa)
- Server: DESKTOP-3AK97A3 (192.168.29.47), v5.1.3.38363
- OpenGL version: 4.6.0 (Intel HD Graphics 520)
- Postman Setup: Authorization: Bearer <vms_token>
I've checked token validity, user permissions, and firewall settings, but I can't seem to resolve the issue. Has anyone else faced this problem or found a workaround? Any insights would be greatly appreciated!

and i still have no luck in “Try it out” page
still getting

{
  "actionParams": "{\"additionalResources\":[\"{20c805c5-42a6-676f-2527-482bcbf3a514}\"],\"allUsers\":false,\"authType\":\"authBasicAndDigest\",\"durationMs\":5000,\"forced\":true,\"fps\":10,\"needConfirmation\":false,\"playToClient\":true,\"recordAfter\":0,\"recordBeforeMs\":1000,\"streamQuality\":\"highest\",\"url\":\"syren1.mp3\",\"useSource\":false}",
  "actionResourceIds": [],
  "actionType": "playSoundOnceAction",
  "aggregationPeriod": 0,
  "comment": "syren",
  "disabled": false,
  "eventCondition": "{\"eventTimestampUsec\":\"0\",\"eventType\":\"undefinedEvent\",\"metadata\":{\"allUsers\":false,\"level\":\"\"},\"omitDbLogging\":false,\"progress\":0,\"reasonCode\":\"none\",\"resourceName\":\"Syren\"}",
  "eventResourceIds": [],
  "eventState": "Undefined",
  "eventType": "userDefinedEvent",
  "id": "{876b9acf-f61d-48cd-8c72-bd6629eda3bc}",
  "schedule": "",
  "system": false
}

and one more thing ur crul call has “\” in the call but when i execute i dont see “\ ” in my curl format

Norman

Network Optix team

May 19, 2025 07:57 Edited
Hi Subramanian,
We noticed that you're currently using an older version of our software, which unfortunately is no longer supported. We kindly recommend updating your VMS to the latest version.
Once you've updated, please take a moment to verify if the reported issues have been resolved. If, however, you find that the problem persists, don't worry. We're more than happy to dive deeper into the matter and assist you further.
If the issue persists, we can convert this topic into a support ticket, so you can share Team Viewer access to the affected system, and we can work from there.
0
Subramanian

May 21, 2025 10:46 Edited
Thank you for your guidance on updating the VMS version. As you suggested, the update resolved the issue, and everything is working smoothly now. I appreciate your prompt assistance!
I do have one more question—currently, it's functioning under the admin user, but is it possible to save events in the live viewer as well and how to set for specific camera ? Please let me know if there's a way to configure this.
Looking forward to your insights.

now i have updated to 6.X
0
Norman

Network Optix team

May 21, 2025 13:27
Hi Subramanian,
Great to hear that everything is resolved!
As for your question, we strongly recommend not using the admin account by default. To create rules, a user must have the Power User access level. This functionality isn’t available to other user levels, except for the local admin or cloud owner accounts — however, using those accounts for this purpose is not advised.
Best regards.
0
Subramanian

May 22, 2025 06:26
"Just a quick update—adding Power User access to the Live User successfully resolved the Save Event issue!"

I truly appreciate your timely assistance.
0
Norman

Network Optix team

May 22, 2025 08:09
Hi Subramanian,
You're welcome.
Please note that assigning both Power User and Live User permissions doesn't really make sense in practice. Typically, assigning users to multiple groups is only useful when working with custom user groups.
Also, I noticed you're using Digest Authentication. Just as a reminder (I assume you already saw the note when creating the user), Digest Authentication has been deprecated. The recommended approach going forward is to use Bearer Authentication. Please keep in mind that Digest Authentication will be fully disabled in the upcoming major release, version 6.1.
With kind regards.
0
Subramanian

May 22, 2025 08:42
is Bearer Authentication is for camera? or login
0
Norman

Network Optix team

May 22, 2025 12:18
Hi Subramanian,
Bearer Authentication is for the VMS. So if you want to create/change/delete anything from the VMS with the API, like adding the Rules, Bearer Authorization if the preferred method.
0

Please sign in to leave a comment.

Trigger Camera Audio Playback via REST API with Custom Sound File in Nx Witness

Comments

Didn't find what you were looking for?