Skip to content

index.md

Latest commit

 

History

History
168 lines (127 loc) · 6.3 KB

index.md

File metadata and controls

168 lines (127 loc) · 6.3 KB

WebTrit Signaling Protocol

The WebTrit Signaling Protocol (WTSP) is designed to establish a reliable, predictable, and self-recoverable mechanism for connecting WebTrit apps to the WebTrit Core.

WTSP utilizes WebSocket as its communication protocol, mandating the specification of the sub-protocol as webtrit-protocol.

WTSP URL structure:

wss://<WebTrit Core host>[:<WebTrit Core port>]/signaling/v1?token=<token>[&force=<true | false (by default)>]

where:

  • token - a session token obtained from the WebTrit Core API
  • force - a flag to define, must current connection close the active one if it exists (true) or not (false)

WTSP message data is a string serialized in the JSON format.

Messages

WTSP classifies messages into the following categories:

  • handshake
    • Direction: server to client and client to server.
    • Purpose: to maintain the current connection with an active client session.
  • request
    • Direction: client to server.
    • Purpose: to execute an action.
    • Logically divided into three groups:
      • Session
      • Line
      • Call
  • response
    • Direction: server to client.
    • Purpose: to acknowledge a received request.
  • event
    • Direction: server to client.
    • Purpose: to notify about the progress of action execution and external events.
    • Logically divided into three groups:
      • Session
      • Line
      • Call

Handshake

Upon successful WebSocket connection, the WebTrit Core server sends the current session's handshake state. Clients should only send requests after receiving this message; failing to do so will result in the WebSocket connection being closed with an appropriate disconnect code.

To promptly detect WebSocket connection issues during idle periods, clients must send a handshake keepalive message at intervals specified in the handshake state. The server echoes the received handshake keepalive.

Request

Key Type Required Description
request string + request type
transaction string + unique transaction identifier of request
line number +1 line number of Line and Call requests (null for guest line)
call_id string +2 call id of Call request
additional request properties if needed

Example

{
  "request": "call",
  "transaction": "transaction-1",
  "line": 0,
  "call_id": "qwertyuiopasdfghjklzxcvbnm",

  "number": "1234567890",
  "jsep": {
    "type": "offer",
    "sdp": "..."
  }
}

Response

Key Type Required Description
response string + response type
transaction string + unique transaction identifier of request
line number +1 line number of Line and Call requests
call_id string +2 call id of Call request
additional response properties, if needed

Example

{
  "response": "ack",
  "transaction": "transaction-1",
  "line": 0
}

Event

Key Type Required Description
event string + event type
transaction string unique transaction identifier of request issued this event
line number +1 line number of Line and Call events
call_id string +2 call id of Call event
additional event properties, if needed

Example

{
  "event": "call",
  "line": 0,
  "call_id": "qwertyuiopasdfghjklzxcvbnm",

  "callee": "0987654321",
  "caller": "1234567890",
  "caller_display_name": "Test User",
  "jsep": {
    "type": "offer",
    "sdp": "..."
  }
}

Logical groups

WTSP organizes its communication into logical groups to handle different aspects of the connection lifecycle and operations. These groups include Session, Line, and Call, each serving a distinct purpose.

Session

A Session represents a unique connection between the WebTrit apps and the WebTrit Core. During the session’s lifecycle, the WebTrit Core establishes and manages a corresponding SIP registration on the SIP server.

Sessions can be classified into two types:

  • permanent: SIP registration persists even without an active session.
  • transient: SIP registration remains active only while the session is active.

By default, all sessions are transient. A session becomes permanent if a push token of a specific type is provided for the WebTrit apps. For more details on push tokens, refer to the /app/push-tokens API.

Line

A Line is a logical container for handling one active call at a time. Lines are identified using the line number property in request, response, and event messages.

Key points about lines:

  • Lines allow WebTrit apps to manage multiple simultaneous calls within a single session.
  • The number of available lines for a session is configured on the WebTrit Core.
  • The current count and state of lines for a particular session can be retrieved from the lines property in the handshake state.
  • The special guest line type exist for making outgoing call with alternate from number. line value for such type of line is null.

Behavior:

  1. Outgoing Calls: To initiate an outgoing call, a free line must be selected. Attempting to place a call on a line with an existing active call will result in an error.
  2. Incoming Calls: Incoming calls are automatically assigned to the first available free line. If all lines are occupied with active calls, the new incoming call will be automatically rejected with the appropriate disconnect code.

Call

A Call represents an active outgoing or incoming call and is identified by the call_id string property in request, response and event messages.

Key characteristics of a call:

  • A call exists within a specific Line.

Features

Self-recoverable mechanism

Walkthrough

Usage examples

Footnotes

  1. Only for Line and Call. ↩ ↩2 ↩3

  2. Only for Call. ↩ ↩2 ↩3