Skip to main content
API docs by Redocly

WebRTC Signal V2 API (2.0.0)

Download OpenAPI specification:Download

Signal manages the WebRTC connections between peers in SME Connect.

answer

Gets an Answer

GET /answer

This request is sent during the WebRTC connections. Once a user has sent an offer to their peer, they will then proceed to poll this answer endpoint until they find an answer from their peer in the Cosmos DB. This endpoint is essential for making successful WebRTC connections.

When troubleshooting WebRTC connections, check if the user polling for a answer from their peer had successfully sent a post /offer request, and that their peer received that /offer.

query Parameters
signalId
string <uuid>

The unique ID (UUID) of the peer the user is trying to connect with

room
string <uuid>
Example: room=00000000-0000-0000-0000-000000000001

The Room UUID the user is in

shortname
stringregex(^[a-z-]+$)
Example: shortname=some-four-word-combination

The Room shortname

cookie Parameters
sess{Unique ID}
required
string
Example: sess{Unique ID}=sess38b9de00=12345678-9abc-4f44-9aba-773c5a9d3465

The session cookie from the Presence service

Responses

Response samples

Content type
application/json
Example
{
  • "from": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "sdp": "v=0\\r\\no=- 4287846699269234128 2 IN IP4 123.0.0.1\\r\\ns=-\\r\\nt=0 0\\r\\na=.......more"
}

Sends an answer

POST /answer

This request is sent during the WebRTC connections. Once a user has received an offer from their peer, they will then send an answer. This answer will be stored in the cosmos DB. This will create a remote answer connection for their peer to get to fully establish a connection with them.

When troubleshooting WebRTC connections, check if the user polling for a answer from their peer had successfully sent a post /offer request, and that their peer received that /offer.

cookie Parameters
sess{Unique ID}
required
string
Example: sess{Unique ID}=sess38b9de00=12345678-9abc-4f44-9aba-773c5a9d3465

The session cookie from the Presence service

Request Body schema: application/json
required

The post request for an answer

to
string <uuid>

The Unique ID (UUID) of the user sending the request to

sdp
string <SDP object>

The Session Description Protocol (SDP) of the peer connection

object

The Room Data with the room UUID and shortname included

Responses

Request samples

Content type
application/json
Example
{
  • "to": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "sdp": "v=0\\r\\no=- 4287846699269234128 2 IN IP4 123.0.0.1\\r\\ns=-\\r\\nt=0 0\\r\\na=.......more",
  • "room": {
    }
}

Response samples

Content type
application/json
Example
{
  • "body": "Invalid id 12345678"
}

expire

Expires the WebRTC Connection

POST /expire

The expire endpoint is called when an SDP needs to be expired between peers. This happens often when a user logs into a room and the endpoint is called to expire any old SDPs that the user may have already had with their peers.

cookie Parameters
sess{Unique ID}
required
string
Example: sess{Unique ID}=sess38b9de00=12345678-9abc-4f44-9aba-773c5a9d3465

The session cookie from the Presence service

Request Body schema: application/json
required

The user will send an object with information on what SDP to expire

source
string <uuid>

UUID of the user requesting expiration

type
string
Enum: "answer" "offer"

The type of SDP -- either an offer or answer

destination
string <uuid>

UUID of the peer

object

The room information

Responses

Request samples

Content type
application/json
Example
{
  • "source": "07b8e003-7027-443f-88b0-24a5eb1cc68b",
  • "type": "answer",
  • "destination": "5332a938-399a-405c-8866-445d97d52324",
  • "room": {
    }
}

Response samples

Content type
application/json
Example
{
  • "body": true
}

ice_servers

Gets ICE Servers

GET /ice_servers

This endpoint sets up the ice_servers that will be critical in allowing a user to send/receive answers/offers from their peers. ICE servers are essential WebRTC components that allow peers to establish connections with each other. They essentially provide the framework for creating connection paths for peers.

When joining a room and connecting with a peer, this is the first endpoint being called. A JSON string is returned with the ICE server information.

cookie Parameters
sess{Unique ID}
required
string
Example: sess{Unique ID}=sess38b9de00=12345678-9abc-4f44-9aba-773c5a9d3465

The session cookie from the Presence service

Responses

Response samples

Content type
application/json
"{\"cfg\":{\"iceCandidatePoolSize\":5,\"iceTransportPolicy\":\"all\",\"iceServers\":[{\"urls\":\"turns:coturn-east.url.dev\",\"hasCredentials\":true,\"username\":\"00000000:turntls\",\"credential\":\"IceServerInfo=\"},{\"urls\":\"turns:coturn-west.url.dev\",\"hasCredentials\":true,\"username\":\"00000000:turntls\",\"credential\":\"IceServerInfo=\"},{\"urls\":\"turn:coturn-east.url.dev\",\"hasCredentials\":true,\"username\":\"00000000:turntls\",\"credential\":\"IceServerInfo=\"},{\"urls\":\"turn:coturn-west.url.dev\",\"hasCredentials\":true,\"username\":\"00000000:turntls\",\"credential\":\"IceServerInfo=\"}]},\"con\":{\"optional\":[{\"DtlsSrtpKeyAgreement\":true}]}}"

login

Logs into Signal

GET /login

The login process occurs once a user has a valid JWT token provided by the auth service. When a user logs into SME Connect, the signal login endpoint will create a valid service session and return a session cookie to the user. This cookie is valid for a 2 hour window. The session cookie stores the user's credentials, which will provide authorization for making WebRTC connections with other users.

Authorizations:
bearerAuth
header Parameters
x-adapt-host
string
x-adapt-handler
string
x-adapt-url
string

Responses

Response samples

Content type
application/json
{
  • "session": {
    }
}

logout

Logs out of Signal

GET /logout

This endpoint will log a user out of signal when a user is logging out of SME Connect. The user's signal session be expired and their cookie will be invalid & removed.

A successful 200 response will have nothing in the response body.

cookie Parameters
sess{Unique ID}
required
string
Example: sess{Unique ID}=sess38b9de00=12345678-9abc-4f44-9aba-773c5a9d3465

The session cookie from the Presence service

Responses

Response samples

Content type
application/json
{
  • "body": "Failed to logout"
}

offer

Gets an Offer

GET /offer

This request is sent during the WebRTC connections. Once a user has entered a room, the user may send an offer to their peer. The user making this request will continue to poll this endpoint until the user receives an offer. This endpoint is essential for making successful WebRTC connections.

When troubleshooting WebRTC connections, check if the user polling for a offer from their peer had successfully sent a post /offer request, and that their peer received that /offer.

query Parameters
signalId
string <uuid>

The unique ID (UUID) of the peer the user is trying to connect with

room
string <uuid>
Example: room=00000000-0000-0000-0000-000000000001

The Room UUID the user is in

shortname
stringregex(^[a-z-]+$)
Example: shortname=some-four-word-combination

The Room shortname

cookie Parameters
sess{Unique ID}
required
string
Example: sess{Unique ID}=sess38b9de00=12345678-9abc-4f44-9aba-773c5a9d3465

The session cookie from the Presence service

Responses

Response samples

Content type
application/json
Example
{
  • "from": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "sdp": "v=0\\r\\no=- 4287846699269234128 2 IN IP4 123.0.0.1\\r\\ns=-\\r\\nt=0 0\\r\\na=.......more"
}

Sends an offer

POST /offer

This request is sent during the WebRTC connections. Once a user has entered a room, the user may send an offer to their peer. This will kickoff the WebRTC exchanges between the user and their peer. Whichever user sends the offer will be the one who will be polling for an answer from the peer.

cookie Parameters
sess{Unique ID}
required
string
Example: sess{Unique ID}=sess38b9de00=12345678-9abc-4f44-9aba-773c5a9d3465

The session cookie from the Presence service

Request Body schema: application/json
required

The post request for an offer

to
string <uuid>

The Unique ID (UUID) of the user sending the request to

sdp
string <SDP object>

The Session Description Protocol (SDP) of the peer connection

object

The Room Data with the room UUID and shortname included

Responses

Request samples

Content type
application/json
Example
{
  • "to": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "sdp": "v=0\\r\\no=- 4287846699269234128 2 IN IP4 123.0.0.1\\r\\ns=-\\r\\nt=0 0\\r\\na=.......more",
  • "room": {
    }
}

Response samples

Content type
application/json
Example
{
  • "body": "Invalid id 12345678"
}