WebSocket API Documentation

The version 2 WebSocket API is currently under construction. Please create tech support tickets as required, we value your feedback.

WebSocket Connection

Where do I find the UserID or ShockerID?

For finding UserID, Tokens, and more see PiShock API Documentation.

[V1 ONLY] When sending a command you MUST stringify it like so:
JSON.stringify(["SUBSCRIBE", JSON.stringify(['1234-ping', '1234-log'])])

Connecting to the WebSocket

To use an API key with the WebSocket, the API key MUST have been generated after the 15th of October 2024 (2024-10-15)

V2

  • Option 1: Username + API Key

    wss://broker.pishock.com/v2?Username={username}&ApiKey={apikey}

  • Option 2: UserId + Token

    wss://broker.pishock.com/v2?UserId={userid}&Token={token}
What is the difference between the two options?

Option 1 (Username + API Key) allows you to login via API credentials, with this option there is no timeout.
Option 2 (UserId + Token) allows you to login as website, with this option your login session will timeout after two (2) weeks.

V1

  • Option 1: Username + API Key

    wss://broker.pishock.com/?username={username}&key={apikey}&api=true

  • Option 2: UserId + Token

    wss://broker.pishock.com/?username=user{userid}&key={token}
What is the difference between the two options?

Option 1 (Username + API Key) allows you to login via API credentials, with this option there is no timeout.
Option 2 (UserId + Token) allows you to login as website, with this option your login session will timeout after two (2) weeks.

Pinging the Broker

To ensure you are successfully connected to the broker, you can use the following command:

V2

{ "Operation":"PING" }
A successful response from a ping will resemble the following:
{ "ErrorCode":null, "IsError":false, "Message":"PONG", "OriginalCommand":"PING" }

V1

[ 'PING' ]
A successful response from a ping will resemble the following:
{ "Command":"PING", "Payload":[ "PONG" ] }

Subscribing to Pings and Logs

Each device has 2 channels you can subscribe to, ping and log. You can subscribe to these channels using one of the following methods:

V2

{ "Operation": "SUBSCRIBE", "Targets":["{clientid1}-ping","{clientid1}-log", "{clientid2}-ping", "{clientid2}-log"] }
Each successful target will respond with the following:
{ "ErrorCode":null,"IsError":false,"Message":"{clientid1}-ping subscribed to.","OriginalCommand":"Original Request JSON" }

V1

[’SUBSCRIBE’, [’{clientid1}-ping’, ’{clientid1}-log’, ’{clientid2}-ping’, ’{clientid2}-log’]]
On success, you will receive the following message:
{"Command":"SUBSCRIBE","Payload":["OK"]}

Unsubscribing

V2

Unsubscribe from all channels
{ "Operation": "UNSUBSCRIBE", "Targets":[ "*" ] }
Unsubscribe from specific channels
{ "Operation": "UNSUBSCRIBE", "Targets":[ "{clientid1}-ping","{clientid1}-log" ] }

V1

Unsubscribe from all channels
[ 'UNSUBSCRIBE', ["*"] ]
Unsubscribe from specific channels
[ 'UNSUBSCRIBE', ["{clientid1}-ping","{clientid1}-log"] ]

Sending Commands

V2

{
	"Operation": "PUBLISH",
	"PublishCommands":
	[
		{
			"Target": "channelhere", //for example c{clientId}-ops or c{clientId}-sops-{sharecode}
			"Body":
			{
				"id": "<shocker.id>",
				"m": "<mode>", // 'v', 's', 'b', or 'e'
				"i": "<intensity>", // Could be vibIntensity, shockIntensity or a randomized value
				"d": "<duration>", // Calculated duration in milliseconds
				"r": "<repeating>", // true or false, always set to true.
				"l":
				{
					"u": "<userID>", // User ID from first step
	                "ty": "<type>", // 'sc' for ShareCode, 'api' for Normal
	                "w": "<warning_flag>", // true or false, if this is a warning vibrate, it affects the logs
	                "h": "<hold>", // true if button is held or continuous is being sent.
	                "o": "<origin>" // send to change the name shown in the logs.
	            }
			}
		}
	]
}
On success, you will receive the following message:
{ "ErrorCode":null,"IsError":false,"Message":"Publish successful.","OriginalCommand":"Original Request JSON" }

V1

Commands are sent in a similar format to Redis.

[
	"PUBLISH",
	[
		[
			'channelhere', //for example c{clientId}-ops or c{clientId}-sops-{sharecode}
			{
				"id": "<shocker.id>",
				"m": "<mode>", // 'v', 's', 'b', or 'e'
				"i": "<intensity>", // Could be vibIntensity, shockIntensity or a randomized value
				"d": "<duration>", // Calculated duration in milliseconds
				"r": "<repeating>", // true or false, always set to true.
				"l": {
					"u": "<userID>", // User ID from first step
					"ty": "<type>", // 'sc' for ShareCode, 'api' for Normal
	                "w": "<warning_flag>", // true or false, if this is a warning vibrate, it affects the logs
	                "h": "<hold>", // true if button is held or continuous is being sent.
	                "o": "<origin>" // send to change the name shown in the logs.
				}
			}
		]
	]
]
Remember to stringify the JSON properly
JSON.stringify([
	"PUBLISH",
	JSON.stringify([
		[
			'channelhere', //for example c{clientId}-ops or c{clientId}-sops-{sharecode}
			JSON.stringify({
				"id": "<shocker.id>",
				"m": "<mode>", // 'v', 's', 'b', or 'e'
				"i": "<intensity>", // Could be vibIntensity, shockIntensity or a randomized value
				"d": "<duration>", // Calculated duration in milliseconds
				"r": "<repeating>", // true or false, always set to true.
				"l": {
					"u": "<userID>", // User ID from first step
					"ty": "<type>", // 'sc' for ShareCode, 'api' for Normal
					"w": "<warning_flag>", // true or false, if this is a warning vibrate, it affects the logs
					"h": "<hold>", // true if button is held or continuous is being sent.
					"o": "<origin>" // send to change the name shown in the logs.
				}
			})
		]
    ])
])
The result will look similar to this before it is sent to the WebSocket:
["PUBLISH","[[\"channelhere\",\"{\\\"id\\\":\\\"<shocker.id>\\\",\\\"m\\\":\\\"<mode>\\\",\\\"i\\\":\\\"<intensity>\\\",\\\"d\\\":\\\"<duration>\\\",\\\"r\\\":\\\"<repeating>\\\",\\\"l\\\":{\\\"u\\\":\\\"<userID>\\\",\\\"ty\\\":\\\"<type>\\\",\\\"w\\\":\\\"<warning_flag>\\\",\\\"h\\\":\\\"<hold>\\\",\\\"o\\\":\\\"<origin>\\\"}}\"]]"]
On success, you will receive the a response similar to this:
{"Command":"PUBLISH","Payload":["PUBLISH SUCCESS"]}