Gravity SMS Docs

WebSocket

Receive real-time SMS delivery status updates and inbound SMS notifications over a persistent WebSocket connection.

WS/wsIn-band API key (first message)

Upgrade to a WebSocket connection for real-time events.

Connection URL

text
wss://smsgateway-api.onrender.com/ws

Authentication

After opening the WebSocket connection, the first message must be an auth message. No other messages are processed until authentication succeeds.

Send (auth)
{
  "type": "auth",
  "apiKey": "sgw_a1b2c3d4e5f6789012345678abcdef90"
}

Success

Receive
{
  "type": "auth_ok"
}

Errors

On auth failure, the server sends an error message and closes the connection with code 1008 (Policy Violation).

Invalid JSON
{
  "type": "auth_error",
  "error": "Invalid JSON"
}
Invalid API key
{
  "type": "auth_error",
  "error": "Invalid API key"
}
Message before auth
{
  "type": "auth_error",
  "error": "Send auth first"
}

Event types

sms_status

Sent when an outbound message changes status (queued → sending → sent/failed).

sms_status — sent
{
  "type": "sms_status",
  "messageId": "msg_a1b2c3d4e5f6",
  "appId": "app_abc123def456abcd",
  "tenantId": "tenant_abc123def456abcd",
  "status": "sent",
  "rcMessageId": "12345678",
  "timestamp": "2026-03-01T10:00:02.000Z"
}
sms_status — failed
{
  "type": "sms_status",
  "messageId": "msg_a1b2c3d4e5f6",
  "appId": "app_abc123def456abcd",
  "tenantId": "tenant_abc123def456abcd",
  "status": "failed",
  "error": "Phone number +15559876543 is not registered in this RingCentral account",
  "timestamp": "2026-03-01T10:00:02.000Z"
}

sms_inbound

Sent when an inbound SMS is received.

sms_inbound
{
  "type": "sms_inbound",
  "messageId": "msg_f6e5d4c3b2a1",
  "from": "+15551234567",
  "to": "+15559876543",
  "body": "Hey, is my appointment still on?",
  "rcMessageId": "12345678",
  "tenantId": "tenant_abc123def456abcd",
  "timestamp": "2026-03-01T14:30:00.000Z"
}

ping

Heartbeat sent by the server every 30 seconds. No response required.

ping
{
  "type": "ping"
}

Event scoping

App role: receives events only for its own tenant.
Admin role: receives events for all tenants.

Example (JavaScript)

javascript
const ws = new WebSocket("wss://smsgateway-api.onrender.com/ws");


ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "auth",
    apiKey: "YOUR_API_KEY"
  }));
};


ws.onmessage = (event) => {
  const data = JSON.parse(event.data);


  switch (data.type) {
    case "auth_ok":
      console.log("Authenticated");
      break;
    case "sms_status":
      console.log("Status update:", data.messageId, data.status);
      break;
    case "sms_inbound":
      console.log("Inbound SMS:", data.from, data.body);
      break;
    case "ping":
      break;
  }
};

Related docs