WebSocket Connection

Generate tokens for real-time live call connections

Overview

Use WebSocket to establish real-time connections for live calls. This endpoint generates short-lived tokens that enable persistent connections for handling inbound and outbound call events within the hospital system.

Transport: Socket.IO using the ws_url and ws_path from POST /api/external/ws-ticket (default ws_path is /ws, not /socket.io).

Purpose: Handle live call connections and call-related events in real-time

Call POST /api/external/ws-ticket to get { token, ws_url, ws_path }. Connect Socket.IO using ws_url, set path to ws_path, and pass token in socket auth.

API Endpoint

POSThttps://server.nyraai.io/api/external/ws-ticket

Generate a short-lived token for WebSocket connection to handle live calls

Permission: ws:ticket

Headers

x-api-keyrequired

API key

x-api-secretrequired

API secret

Authorizationrequired

Bearer hospital token

Response

{
  "success": true,
  "data": {
    "token": "short_lived_jwt_for_ws",
    "ws_url": "https://server.nyraai.io",
    "ws_path": "/ws"
  }
}

Live Call Connection

Step 1: Generate WebSocket Token

Request a WebSocket token from the API to establish a connection for live calls:

curl -X POST "https://server.nyraai.io/api/external/ws-ticket" \
  -H "x-api-key: nyra_..." \
  -H "x-api-secret: secret..." \
  -H "Authorization: Bearer token..."

Step 2: Connect with Socket.IO

Use ws_url, ws_path, and token from the ticket response. Set the client path option to ws_path so the client does not default to /socket.io.

import { io } from 'socket.io-client';

const { token, ws_url, ws_path } = ticketData; // from Step 1

const socket = io(ws_url, {
  path: ws_path,
  auth: { token },
  transports: ['websocket'],
});

socket.on('connect', () => {
  console.log('Connected to live call service');
});

socket.on('connect_error', (err) => {
  console.error('Connection error:', err);
});

socket.onAny((event, payload) => {
  console.log('Event:', event, payload);
});

Node.js Complete Example

import { io } from 'socket.io-client';

const getWSTicket = async () => {
  const response = await fetch(
    'https://server.nyraai.io/api/external/ws-ticket',
    {
      method: 'POST',
      headers: {
        'x-api-key': process.env.API_KEY,
        'x-api-secret': process.env.API_SECRET,
        'Authorization': `Bearer ${process.env.HOSPITAL_TOKEN}`
      }
    }
  );

  const result = await response.json();
  return result.data;
};

const connectLiveCallService = async () => {
  const { token, ws_url, ws_path } = await getWSTicket();

  const socket = io(ws_url, {
    path: ws_path,
    auth: { token },
    transports: ['websocket'],
  });

  socket.on('connect', () => {
    console.log('Connected to live call service');
  });

  socket.on('connect_error', (error) => {
    console.error('Connection error:', error);
  });

  socket.on('disconnect', () => {
    console.log('Live call connection closed');
  });

  // handleCallEvent(socket, eventName, payload);
};

connectLiveCallService();

Important Notes

Token Lifespan

WebSocket tokens are short-lived. Request a new token before expiry to maintain continuous connection for live calls.

Authentication Required

All three external headers (x-api-key, x-api-secret, and Authorization: Bearer with the hospital token from key issuance) are required to obtain a WebSocket JWT from this endpoint.

Live Call Events

Connected clients receive real-time events for inbound calls, outbound calls, and call terminations.

Socket path

Always use the server-provided ws_path (often /ws) as the Socket.IO path option. Do not rely on the default /socket.io path.

Reconnection Logic

Implement automatic reconnection with exponential backoff for handling network failures during live calls.

Request/Response Reference

Request

HTTP Request

POST /api/external/ws-ticket HTTP/1.1
Host: server.nyraai.io
x-api-key: nyra_2f9a1e2b3c4d5f6g7h8i
x-api-secret: aVeryLongBase64SecretString...
Authorization: Bearer <hospital_token_from_key_issuance>

(empty body - no request payload needed)

Success Response (200)

Returns a token and WebSocket URL for live call connections:

{
  "success": true,
  "data": {
    "token": "short_lived_jwt_for_ws",
    "ws_url": "https://server.nyraai.io",
    "ws_path": "/ws"
  }
}

Error Response (401)

Returned when authentication fails:

{
  "success": false,
  "error": "Unauthorized",
  "message": "Invalid API credentials"
}

Error Response (403)

Returned when API key lacks ws:ticket permission:

{
  "success": false,
  "error": "Forbidden",
  "message": "Missing required permission: ws:ticket"
}

Sample Live Call Events

After connecting to the WebSocket, you will receive live call events with the following structures:

Inbound Call Event

{
  "type": "inbound_call",
  "data": {
    "call_id": "call-uuid",
    "patient_id": "patient-uuid",
    "phone_number": "9876543210",
    "branch_id": "branch-uuid",
    "timestamp": "2026-04-08T10:30:00Z"
  }
}

Outbound Call Event

{
  "type": "outbound_call",
  "data": {
    "call_id": "call-uuid",
    "patient_id": "patient-uuid",
    "phone_number": "9876543210",
    "call_type": "reminder",
    "branch_id": "branch-uuid",
    "timestamp": "2026-04-08T10:30:00Z"
  }
}

Call Ended Event

{
  "type": "call_ended",
  "data": {
    "call_id": "call-uuid",
    "duration": 245,
    "status": "completed",
    "timestamp": "2026-04-08T10:35:00Z"
  }
}