Skip to main content

JSON-RPC API

The SDK exposes a JSON-RPC dispatcher that maps directly to the C++ Switchboard API. Send a JSON request in, get a JSON response out — no language binding required. This is what the Switchboard WebSocket Server speaks over the wire, but you can also instantiate the dispatcher in-process and use it as a string-in / string-out interface.

Request shape​

{
  "id": 12,
  "method": "createEngine",
  "params": { ... }
}
  • id — optional, integer or string. If present it's echoed back on the response so async callers can correlate.
  • method — required. One of the methods listed below.
  • params — required. Method-specific object.

Response shape​

Success:

{
  "id": 12,
  "result": <method-specific value>
}

Error:

{
  "id": 12,
  "error": { "message": "Unknown method: value" }
}

The result value matches what the corresponding C++ call returns: an object ID string for createEngine, an arbitrary value for getValue / callAction, null for void-returning methods.

Methods​

The dispatcher accepts the same nine methods as the SDK call surface. The params shape mirrors the C++ argument names.

initialize​

{ "method": "initialize", "params": { "config": { "appID": "...", "appSecret": "..." } } }

deinitialize​

{ "method": "deinitialize", "params": {} }

createEngine​

{
  "method": "createEngine",
  "params": {
    "config": {
      "type": "Realtime",
      "config": {
        "graph": {
          "nodes": [ /* ... */ ],
          "connections": [ /* ... */ ]
        }
      }
    }
  }
}

Result is the new engine's object ID:

{ "id": 12, "result": "engine-1" }

destroyEngine​

{ "method": "destroyEngine", "params": { "engineID": "engine-1" } }

callAction​

objectID (or objectURI) and actionName are required. params is optional and forwarded to the action.

{
  "method": "callAction",
  "params": {
    "objectID": "engine-1",
    "actionName": "getState"
  }
}
{
  "method": "callAction",
  "params": {
    "objectID": "playerNode",
    "actionName": "load",
    "params": { "audioFilePath": "AudioFiles/speech-mono-48k.wav" }
  }
}

setValue​

{
  "method": "setValue",
  "params": {
    "objectID": "playerNode",
    "key": "isLoopingEnabled",
    "value": true
  }
}

getValue​

{
  "method": "getValue",
  "params": {
    "objectID": "recorderNode",
    "key": "framesRecorded"
  }
}

addEventListener​

Returns a listener ID. Events are not delivered in the response — they arrive through the event callback (see below).

{
  "method": "addEventListener",
  "params": {
    "objectID": "playerNode",
    "eventName": "playbackProgress"
  }
}

removeEventListener​

{
  "method": "removeEventListener",
  "params": {
    "objectID": "playerNode",
    "listenerID": 7
  }
}

Events​

Subscriptions registered via addEventListener deliver event JSON through a separate callback channel, not through method responses. The shape of each event payload is method-specific. Over WebSocket, events arrive as server-pushed messages on the same socket.

Embedding the dispatcher​

The C++ class is switchboard::SwitchboardJSONRPC. Each instance is a session — typically one per connected client.

#include <switchboard/SwitchboardJSONRPC.hpp>

switchboard::SwitchboardJSONRPC session;

session.setEventCallback([](const std::string& eventJSON) {
    // forward to your transport (e.g. WebSocket.send(eventJSON))
});

std::string response = session.processCommand(requestJSON);
// forward `response` back to the caller

session.clearEventCallback();

WebSocket server​

The reference WebSocket server in SwitchboardWebSocketServer.cpp creates one SwitchboardJSONRPC per connected session and pipes every received text frame through processCommand. Event-callback output is sent back to the same socket as a server-push frame. Use it as a reference implementation for embedding the dispatcher into any other transport (HTTP, IPC, named pipe, etc.).

Full Reference​

Open C++ API Reference — SwitchboardJSONRPC class