WebSocket API

The XPARO WebSocket API enables real-time communication between robots, clients, and the XPARO platform.

Unlike REST, WebSocket maintains a persistent connection that allows the server to push updates instantly.

WebSocket endpoint

` wss://xparo-website.onrender.com/ws/chatbot/<secret_key>/<project_id>/ `

Connection flow

Client connects to the WebSocket endpoint.
Server authenticates using secret_key and project_id.
Server may push configuration updates immediately.
Client sends messages; the server responds or pushes asynchronous events.

Message format

All messages are JSON objects.

Basic structure:

{
  "type": "message_type",
  "data": {}
}

Client → Server examples

Chat

{
  "type": "chat",
  "data": {
    "message": "Hello robot",
    "robot_id": "robot_123"
  }
}

Server response:

{
  "type": "chat_response",
  "data": {
    "response": "Hello, how can I assist you?"
  }
}

Telemetry update

{
  "type": "telemetry",
  "data": {
    "cpu_usage": 42,
    "memory_usage": 63,
    "disk_usage": 31
  }
}

Server → Client events

Chat response

{
  "type": "chat_response",
  "data": {
    "response": "Navigation command received"
  }
}

Behavior tree update

{
  "type": "behavior_update",
  "data": {
    "tree_name": "MainTree",
    "xml": "<BehaviorTree>...</BehaviorTree>"
  }
}

Remote control

{
  "type": "remote_command",
  "data": {
    "command": "start_navigation",
    "parameters": {
      "goal": "table_4"
    }
  }
}

Logging session start

{
  "type": "log_updated",
  "data": {
    "session_id": "session_987"
  }
}

REST token update

{
  "type": "REST_API_TOKEN",
  "data": {
    "token": "abcdef123456"
  }
}

Heartbeat

Server ping:

{ "type": "ping" }

Client should reply with:

{ "type": "pong" }

Example Python client

import websocket
import json

url = "wss://xparo-website.onrender.com/ws/chatbot/SECRET/PROJECT/"

def on_message(ws, message):
    data = json.loads(message)
    print("Received:", data)

def on_open(ws):
    payload = {
        "type": "chat",
        "data": {
            "message": "Hello robot"
        }
    }
    ws.send(json.dumps(payload))

ws = websocket.WebSocketApp(
    url,
    on_message=on_message
)

ws.run_forever()