Websocket Messaging Protocol

This page documents the websocket protocol implemented by the Patriot Websocket Messaging task. Implement this protocol in your Messaging Bridge server to send and receive messages through Patriot.

Patriot always acts as the websocket client and connects out to your server. All messages are JSON encoded text frames of the form:

interface WebsocketMessage {
  type: string;
  payload?: object;
}

Messages Patriot does not recognise, and non-text frames, are logged and ignored - your server may safely be extended with additional message types.

Connection Setup

Patriot opens the websocket connection to the Websocket URL configured in the task settings, sending any configured Headers as HTTP headers on the upgrade request. See Websocket Messaging Task Settings.

Initialisation

Once connected, Patriot sends an Init message containing the Websocket Config value from the task settings. Your server must respond with an InitResponse indicating whether initialisation succeeded.

• Patriot waits up to 15 seconds for the InitResponse. If none arrives, the connection attempt is abandoned and retried on the next task cycle.
• If your server responds with success: false, the task is placed into a fault state and the error value is logged.
• If the connection drops, Patriot reconnects and re-sends the Init message.

Until initialisation succeeds Patriot will not send any messages other than Init.

Immediately after a successful InitResponse, Patriot sends SubscribeToMessageDeliveryStatuses listing every message still awaiting a final delivery status. This allows delivery results to survive a restart of the messaging bridge service.

Heartbeats

Patriot sends a Heartbeat once per task cycle - approximately every 5 seconds. Your server must reply with a HeartbeatResponse to confirm the connection is healthy.

If the previous heartbeat was not answered by the time the next one is due, the task is placed into a fault state. The fault is cleared when a HeartbeatResponse is next received.

Message Definitions

Connection Messages

Init

Sent from Patriot to the Messaging Bridge to upgrade to an initialised (authenticated) socket.

interface Init {
  type: 'init';
  payload: {
    /**
     * The Websocket Config task setting, passed through as a JSON string.
     * Server specific - your server must parse this string to read its values.
     */
    config: string;
  };
}

Example

{
  "type": "init",
  "payload": {
    "config": "{\"userName\":\"123456\",\"password\":\"ABC123DEF456\"}"
  }
}

note

config is a string containing JSON, not a nested JSON object. This lets the config schema be defined entirely by your server without Patriot needing to understand it.

Init Response

Sent from the Messaging Bridge to Patriot to acknowledge an Init message.

interface InitResponse {
  type: 'init-response';
  payload: {
    success: boolean;
    /**
     * Reason for failure. Logged by Patriot and included in the task fault description.
     */
    error?: string;
  };
}

Example

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

Heartbeat

Sent from Patriot to the Messaging Bridge once per task cycle to test the connection status.

interface Heartbeat {
  type: 'heartbeat';
}

Example

{
  "type": "heartbeat"
}

Heartbeat Response

Sent from the Messaging Bridge to Patriot to acknowledge a Heartbeat and confirm the connection status is normal.

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

Example

{
  "type": "heartbeat-response"
}

Outbound Message Messages

Send Message

Sent from Patriot to the Messaging Bridge to request a message be delivered.

The messageId is allocated by Patriot and is unique per message. Your server must use it in all MessageDeliveryStatusUpdate messages for this message.

interface SendMessage {
  type: 'send-message';
  payload: {
    /**
     * Unique Id, generated by Patriot.
     */
    messageId: string;
    destination: string;
    content: string;
  };
}

Example

{
  "type": "send-message",
  "payload": {
    "messageId": "10542",
    "destination": "+64211234567",
    "content": "Burglary Alarm at 12 Example St, Zone 3"
  }
}

Message Delivery Status Update

Sent from the Messaging Bridge to Patriot to report the delivery state of a message.

Your server should send a status update whenever the state of a message changes, and must eventually send either success or error for every message - Patriot treats a message as in flight until it does, and will re-subscribe to it after a reconnect.

interface MessageDeliveryStatusUpdate {
  type: 'message-delivery-status-update';
  payload: {
    /**
     * messageId from the corresponding SendMessage message.
     */
    messageId: string;
    status: 'success' | 'pending' | 'error';
    /**
     * Additional detail. Logged by Patriot, recommended when status is 'error'.
     */
    info?: string;
  };
}

Status	Patriot behaviour
success	The message is recorded as successfully sent and Patriot sends UnsubscribeFromMessage.
pending	Logged only. The message remains in flight.
error	The message is recorded as a failed send, subject to the task's Attempts / Retries settings, and Patriot sends UnsubscribeFromMessage.

Any other status value is logged as a warning and otherwise ignored.

Example

{
  "type": "message-delivery-status-update",
  "payload": {
    "messageId": "10542",
    "status": "error",
    "info": "Destination number unreachable"
  }
}

Subscribe To Message Delivery Statuses

Sent from Patriot to the Messaging Bridge immediately after a successful InitResponse, listing every message that has not yet reached a final delivery status.

Your server should respond by sending the current MessageDeliveryStatusUpdate for each listed message, and continue reporting status changes for them. The list is empty when there are no messages in flight.

interface SubscribeToMessageDeliveryStatuses {
  type: 'subscribe-to-message-delivery-statuses';
  payload: {
    messageIds: string[];
  };
}

Example

{
  "type": "subscribe-to-message-delivery-statuses",
  "payload": {
    "messageIds": ["10542", "10543"]
  }
}

Unsubscribe From Message

Sent from Patriot to the Messaging Bridge once a message has reached a final delivery status (success or error). Your server should stop sending status updates for the message.

interface UnsubscribeFromMessage {
  type: 'unsubscribe-from-message';
  payload: {
    messageId: string;
  };
}

Example

{
  "type": "unsubscribe-from-message",
  "payload": {
    "messageId": "10542"
  }
}

Inbound Message Messages

Message Received

Sent from the Messaging Bridge to Patriot to deliver an inbound message, for example an SMS reply from a response member.

Patriot processes the message according to the task's Recv. Message Type setting - see Receiving Messages Back. The message is first tested against the Patriot Standard Message format, then (if configured) the First Response format, and otherwise processed with the task's message formats.

Received messages are logged as Received SMS signals, with raw data in the form From: <source>, Message: <content>.

interface MessageReceived {
  type: 'message-received';
  payload: {
    /**
     * Your server's id for this inbound message. Echoed back in MessageReceivedAck.
     */
    messageId: string;
    /**
     * The address the message was received from.
     */
    source: string;
    content: string;
  };
}

Example

{
  "type": "message-received",
  "payload": {
    "messageId": "in-9981",
    "source": "+64211234567",
    "content": "ACK 3"
  }
}

Message Received Ack

Sent from Patriot to the Messaging Bridge to confirm an inbound message has been processed. Your server should not deliver the same message again once acknowledged.

No acknowledgement is sent if processing the inbound message fails, so your server may re-deliver unacknowledged messages after a reconnect.

interface MessageReceivedAck {
  type: 'message-received-ack';
  payload: {
    /**
     * messageId from the corresponding MessageReceived message.
     */
    messageId: string;
  };
}

Example

{
  "type": "message-received-ack",
  "payload": {
    "messageId": "in-9981"
  }
}

Related Pages

• Websocket Messaging Task
• Autodialler API Protocol
• Instant Messaging Tasks