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 either Desktop API Dialler (Patriot as Server) or Websocket Client Dialler (Patriot as Client).

note

Some API messages are only applicable when Patriot is acting in a particular mode (client or server). Where this is the case it will be indicated in the Message Definition.

It is recommended to integrate with Patriot acting as the websocket client since these integrations will be compatible with the Patriot web client (ICA) in addition to the Patriot Windows desktop client.

Patriot as Server

When using the server implementation the Patriot Desktop Client hosts a websocket based API at a url in the form:

wss://desktop-client-api.patriotsystems.com:<port-number>/ws/dialler/v1

note

A public DNS record exists to direct the URL desktop-client-api.patriotsystems.com to 127.0.0.1 (i.e. localhost). If a public DNS lookup is not suitable then a DNS lookup must be configured in a local network DNS server or per machine via the windows HOSTS file.

The Patriot Client automatically generates a self-signed SSL certificate and prompts users to add this to their personal Trusted Root Certificates store.

The port-number defaults to 9009 but can be configured with the WebSocketServerPort setting in the Patriot Client .config file.

Authentication

Once a connection has been established with Patriot the Dialler Client must first send an AuthenticationRequest message (see Message Definitions) containing a valid ApiKey (configured per client with the WebSocketApiKey setting in the Patriot Client .config file). Patriot will respond with an AuthenticationResponse message indicating if the request was successful or not.

Until a valid AuthenticationResponse has been received Patriot will ignore any non AuthenticationRequest messages.

Patriot as Client

When using the client implementation the Patriot Client will connect out to a Dialler Server implementing this API. The server url is set with the WebSocketClientDiallerUrl setting in the Patriot Client .config file. For secure connections (wss://) the Dialler Server certificate must be trusted by the Patriot client machine.

Initialization/Authentication

Once the Patriot Client establishes a connection with the Dialler Server it will send a InitRequest message (see Message Definitions) containing server specific configuration for the Patriot Client in JSON format. The JSON configuration is set with the WebSocketClientDiallerConfig setting in the Patriot Client .config file. Normally this configuration will include authentication details (e.g. username and password). The Dialler Server should respond with an InitResponse message indicating whether the initialisation (including authentication if applicable) was successful. If no response is received to an InitRequest within 30 seconds Patriot will re-send the InitRequest message. If the websocket connection is broken Patriot will automatically attempt to re-establish the connection and re-send the InitRequest message.

Heartbeat

The Patriot Client will send a Heartbeat message every 5 seconds to the Dialler Server to confirm connectivity. The Dialler Server should respond with a HeartbeatResponse to confirm the connection is healthy.

Message Definitions

AuthenticationRequest (Patriot as Server only)

Sent from Dialler Client to Patriot to upgrade to an authenticated socket.

interface AuthenticationRequest {
  type: 'authentication-request';
  payload: {
    /**
     * Optional. If specified then the corresponding AuthenticationResponse will include this requestId.
     */
    requestId?: string;
    apiKey: string;
  };
}

Example

{
  "type": "authentication-request",
  "payload": {
    "requestId": "123456",
    "apiKey": "ABC123DEF456"
  }
}

AuthenticationResponse

Sent from Patriot to Dialler Client to acknowledge an Authentication Request

interface AuthenticationResponse {
  type: 'authentication-response';
  payload: {
    /**
     * requestId from the corresponding AuthenticationRequest message.
     */
    requestId: string;
    success: boolean;
    error?: string;
  };
}

Example

{
  "type": "authentication-response",
  "payload": {
    "requestId": "123456",
    "success": true
  }
}

InitRequest (Patriot as Client only)

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
  }
}

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 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 below).

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 Call Status Request messages (see above).

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"
  }
}

Heartbeat (Patriot as Client only)

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"
}