Key Concepts for Clients and Rooms

To better organize credentials, TURN sessions, and TURN usage, we provide two types of additional parameters. You can include these parameters when obtaining an ICE connection string:

• clients
• rooms

---

Clients

When requesting credentials from the Turnix TURN‑STUN service, you can specify two different types of clients:

1. Initiator Client The initiator is responsible for starting the WebRTC connection.

2. Receiver Client The receiver is the client that receives the incoming connection initiated by another client.

By specifying the initiator and receiver clients, you can more easily track and log each role in the Turnix Console.

---

Rooms

A “room” is an organizational grouping that can contain any number of clients. You can specify a room name when requesting credentials. Rooms allow you to:

• Organize multiple client connections under a common identifier.
• Quickly find related client sessions within the Turnix Console.
• Potentially link back to your own system by associating the room name with specific data or application modules.

Limitations

You can provide any type of string for your room or clients: a name, an ID, or anything else you want to track later. The maximum length is 100 characters, and no special characters are allowed. Only letters, numbers, -, and _ are permitted.

---

Using Clients and Rooms

1. Credentials Request When requesting TURN/STUN credentials, you can supply:

   • Initiator Client: The client initiating the connection.
   • Receiver Client: The client receiving the connection.
   • Room: A grouping identifier for monitoring and organizational purposes.

CURL

curl -X POST \
  https://turnix.io/api/v1/credentials/ice \
  -H 'Authorization: Bearer YOUR_API_BEARER_TOKEN' \
  -d 'initiator_client=OPTIONAL_INITIATOR_CLIENT_VALUE' \
  -d 'receiver_client=OPTIONAL_RECEIVER_CLIENT_VALUE' \
  -d 'room=OPTIONAL_ROOM_NAME_VALUE'

Ruby

require 'httparty'

response = HTTParty.post(
  "https://turnix.io/api/v1/credentials/ice",
  headers: {
    "Authorization" => "Bearer YOUR_API_BEARER_TOKEN"
  },
  body: {
    initiator_client: "OPTIONAL_INITIATOR_CLIENT_VALUE",
    receiver_client: "OPTIONAL_RECEIVER_CLIENT_VALUE",
    room: "OPTIONAL_TEAM_NAME_VALUE"
  }
)

puts response.code      # HTTP status code
puts response.body      # Response body

Node.js

const fetch = require('node-fetch');

(async () => {
  try {
    const response = await fetch('https://turnix.io/api/v1/credentials/ice', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_BEARER_TOKEN',
        'Content-Type': 'application/x-www-form-urlencoded'
      },
      body: new URLSearchParams({
        initiator_client: 'OPTIONAL_INITIATOR_CLIENT_VALUE',
        receiver_client: 'OPTIONAL_RECEIVER_CLIENT_VALUE',
        room: 'OPTIONAL_TEAM_NAME_VALUE'
      })
    });

    if (!response.ok) {
      throw new Error(`Request failed with status ${response.status}`);
    }

    const data = await response.json();
    console.log('Response:', data);
  } catch (error) {
    console.error('Error:', error.message);
  }
})();

Dart

import 'package:http/http.dart' as http;
import 'dart:convert';

final apiToken = 'YOUR_API_TOKEN';

final response = await http.post(
  Uri.parse('https://turnix.io/api/v1/credentials/ice'),
  headers: {
    'Authorization': 'Bearer $apiToken',
    'Content-Type': 'application/json',
  },
  body: json.encode({
    'initiator_client': 'OPTIONAL_INITIATOR_CLIENT_VALUE',
    'receiver_client': 'OPTIONAL_RECEIVER_CLIENT_VALUE',
    'room': 'OPTIONAL_ROOM_NAME_VALUE',
  }),
);

final body = json.decode(response.body);
print(body);

Java

import java.net.URI;
import java.net.http.*;
import java.time.Duration;

HttpClient client = HttpClient.newHttpClient();
String apiToken = "YOUR_API_TOKEN";

JSONObject body = new JSONObject()
    .put("initiator_client", "OPTIONAL_INITIATOR_CLIENT_VALUE")
    .put("receiver_client", "OPTIONAL_RECEIVER_CLIENT_VALUE")
    .put("room", "OPTIONAL_ROOM_VALUE");

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://turnix.io/api/v1/credentials/ice"))
    .header("Authorization", "Bearer " + apiToken)
    .header("Accept", "application/json")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body.toString()))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

2. Monitoring in Turnix Console After you have created rooms and assigned clients to them, the Turnix Console allows you to:

   • View active connections grouped by room.
   • Track usage statistics and connection details per client.
   • Create direct links from the console back to your own system for further analysis or debugging.

3. Handling Multiple Connections Since a room can hold any number of clients, you can have numerous connections (both initiators and receivers) within the same room. This approach is particularly useful for applications that manage multiple parallel sessions under a single context—such as group calls, conference rooms, or multi‑user sessions.

---

Example Workflow

1. Request Credentials

   • Initiator requests credentials, specifying client_type = initiator and room = "exampleRoomA".
   • Receiver requests credentials, specifying client_type = receiver and room = "exampleRoomA".

2. Establish Connection

   • The initiator’s WebRTC connection uses the provided TURN/STUN credentials and attempts to establish a peer‑to‑peer session.
   • The receiver, using its own credentials, waits for the incoming connection.

3. Monitor in Console

   • Log in to the Turnix Console, and navigate to “Rooms”.
   • Select “exampleRoomA” to view all clients within this room. You will see both the initiator and the receiver listed, including relevant statistics such as connection duration, data usage, and NAT traversal information.

4. Create Direct Links

   • By associating a client’s credentials with an ID in your own database, you can configure direct links from the Turnix Console back to your application. This allows you to quickly jump from Turnix monitoring to your own logs or troubleshooting tools.

---

Best Practices

• Use Meaningful Names When specifying clients and rooms, choose descriptive identifiers. This helps with debugging and makes it easier to correlate sessions with your application’s logs.

• Limit Scope of Credentials Generate credentials with appropriate time‑to‑live (TTL) values or usage limits. This prevents unauthorized use and improves security.

• Monitor & Scale Regularly check the Turnix Console to ensure connections are performing as expected. If you notice high load or connection failures, consider scaling your TURN/STUN infrastructure accordingly.

• Secure Your Endpoints Always use secure protocols (e.g., TLS) when connecting to the Turnix service, and follow industry best practices to protect your credentials from unauthorized access.

---

Conclusion

By leveraging the Turnix TURN‑STUN service with well‑defined clients and rooms, you can offer a reliable WebRTC‑based communication platform. Detailed metrics and the ability to create direct links from the console to your own system make it easier to monitor, troubleshoot, and refine your real‑time communication workflows.

For additional details or advanced configuration options, please refer to the Turnix Official Documentation or contact our support team.