Skip to main content
Version: 6.13

Autodialler API Protocol

The Patriot desktop client can implement this protocol by acting as either a websocket server or client. This is controlled by which module you have registered: WebsocketClientDialler (Patriot as Client) or DesktopApiDialler (Patriot as Server).

:::tip Recommended: Patriot as Client

Integrating with Patriot acting as the websocket client is the recommended approach. These integrations will be compatible with both the Patriot web client (ICA) and the Patriot Windows desktop client.

:::

In this mode Patriot connects out to your Dialler Bridge server. The bridge translates Patriot API messages into commands for your phone system.

Configuration​

The following settings are configured in the Patriot Client .config file (typically PatriotMVVM.exe.config):

SettingValue
DiallerTypeWebsocketClient
WebSocketClientDiallerUrlWebSocket URL of your Dialler Bridge server (e.g. wss://bridge.example.com/dialler)
WebSocketClientDiallerConfigJSON string passed as the payload of the InitRequest — typically contains authentication credentials required by your bridge

Example .config snippet:

<setting name="DiallerType" serializeAs="String">
    <value>WebsocketClient</value>
</setting>
<setting name="WebSocketClientDiallerUrl" serializeAs="String">
    <value>wss://bridge.example.com/dialler</value>
</setting>
<setting name="WebSocketClientDiallerConfig" serializeAs="String">
    <value>{"userName": "123456", "password": "ABC123DEF456"}</value>
</setting>
note

For secure connections (wss://) the Dialler Bridge server's certificate must be trusted by the Patriot client machine.

Connection Setup​

The Patriot Client connects out to a Dialler Server implementing this API.

Initialization / Authentication​

Once connected, Patriot sends an InitRequest containing server-specific configuration in JSON format, set via the WebSocketClientDiallerConfig setting in the Patriot Client .config file.

The Dialler Server must respond with an InitResponse indicating whether initialization was successful.

  • If no response is received within 30 seconds, Patriot re-sends the InitRequest.
  • If the connection is broken, Patriot automatically reconnects and re-sends the InitRequest.

Patriot also sends a Heartbeat message every 5 seconds. The Dialler Server should respond with a HeartbeatResponse to confirm the connection is healthy.

Message Definitions​

Connection Messages​

InitRequest​

Sent from Patriot to Dialler Server to upgrade to an initialized (authenticated) socket.

interface InitRequest {
  type: 'init-request';
  payload: {
    /**
     * Server specific
     */
  };
}

Example

{
  "type": "init-request",
  "payload": {
    "userName": "123456",
    "password": "ABC123DEF456"
  }
}

InitResponse​

Sent from Dialler Server to Patriot to acknowledge an Init Request.

interface InitResponse {
  type: 'init-response';
  payload: {
    success: boolean;
    error?: string;
  };
}

Example

{
  "type": "init-response",
  "payload": {
    "success": true
  }
}

Heartbeat​

Sent from Patriot to Dialler Server every five seconds to test the connection status.

interface Heartbeat {
  type: 'heartbeat';
}

Example

{
  "type": "heartbeat"
}

Heartbeat Response​

Sent from Dialler Server to Patriot to acknowledge a Heartbeat and confirm the connection status is normal.

interface HeartbeatResponse {
  type: 'heartbeat-response';
}

Example

{
  "type": "heartbeat-response"
}

Call Control Messages​

These messages apply to both integration modes.

DialRequest​

Sent from Patriot to Dialler to request an outgoing call to be initiated.

interface DialRequest {
  type: 'dial-request';
  payload: {
    // The phone number to dial.
    // NOTE: this is a sanitised version of the user entered phone
    // number and will include only the characters 0-9, '+', '*' and '#'.
    phoneNo: string;
    // The raw user entered phone number
    rawPhoneNo: string;
  };
}

Example

{
  "type": "dial-request",
  "payload": {
    "phoneNo": "+0123456789",
    "rawPhoneNo": "+01 (2) 3-456-789"
  }
}

HangupRequest​

Sent from Patriot to Dialler to request the current call to be ended.

interface HangupRequest {
  type: 'hangup-request';
}

Example

{
  "type": "hangup-request"
}

CallStatusRequest​

Sent from Patriot to Dialler to request a Call Status Update (see CallStatusUpdate).

interface CallStatusRequest {
  type: 'call-status-request';
}

Example

{
  "type": "call-status-request"
}

CallStatusUpdate​

Sent from Dialler to Patriot to inform of Call Status Updates. This should be sent on status changes as well as in response to CallStatusRequest messages.

interface CallStatusUpdate {
  type: 'call-status-update';
  payload: {
    callActive: boolean;
    outbound?: boolean;
    callerId?: string;
  };
}

Example

{
  "type": "call-status-update",
  "payload": {
    "callActive": true,
    "outbound": true,
    "callerId": "123-456-789"
  }
}