Desktop API Dialler Protocol

When using the Desktop API Dialler 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 below) 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 sent Patriot will ignore any non AuthenticationRequest messages.

Message Definitions

AuthenticationRequest

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

DialRequest

Sent from Patriot to Dialler Client 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 Client to request current call to be ended.

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

Example

{
  "type": "hangup-request"
}

CallStatusRequest

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

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

Example

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

CallStatusUpdate

Sent from Dialler Client 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"
  }
}