Applies To
Vonage Video API
Location Hint
Session Creation
Routed Sessions
Relayed Sessions
Question
How does the Vonage Video API decide where to place the session control server when I create a session? What does the Location Hint parameter do, and how is it different from media routing?
Session Control and Media Routing Are Two Separate Things
This is the most important concept to understand before diving into Location Hint.
A Vonage Video API session involves two completely independent layers:
Layer |
What It Does |
Controlled By |
|---|---|---|
Session Control (Signalling) |
Manages session state, participant join/leave events, and signalling between clients and the platform |
Location Hint (optional) |
Media Routing |
Routes audio and video streams between participants via SFUs (Selective Forwarding Units) |
Media Mesh (automatic) |
Session control and media routing are independent. Where the session control server is placed has no effect on where media flows, and vice versa. Optimising one does not optimise the other.
How a Session Lands in a Session Control Server
When you create a session using the Vonage Video API REST endpoint, the platform assigns a session control server to manage that session for its entire lifetime. Here is exactly how that placement works in each scenario:
Without a Location Hint
When no location parameter is passed at session creation:
When the first participant joins a session, the platform selects a session control server based on the participant's IP address and the platform's internal availability, which typically will be the nearest server to that participant.
Participants can still join from anywhere in the world, but signalling may travel a longer distance, which can add latency to session events.
Examples:
Example |
First Participant |
Server Assigned |
Impact |
|---|---|---|---|
Ex 1 |
Europe (capacity available) |
Europe |
All signalling for US participants travels between Europe and the US |
Ex 2 |
India (no capacity in region) |
Australia (nearest available) |
All signalling for US participants travels to and from Australia |
With a Location Hint
When you pass an IP address as the location parameter at session creation:
The platform identifies the datacenter geographically closest to that IP address, regardless of the first participant's IP address.
The session control server is placed in that datacenter — on a best-effort basis.
If the preferred datacenter is at capacity, the platform may fall back to the next closest available datacenter.
Example: You are hosting a webinar where most attendees are in Europe, but you are in the USA. You pass a European IP address as the location hint when creating the session. The platform places the session control server in a European datacenter, reducing signalling latency for your audience.
POST https://api.opentok.com/session/create
location=<european_ip_address>Note: Location Hint is a preference, not a guarantee. If the closest datacenter is unavailable, the platform will use the next best option.
What Location Hint Does NOT Do
Common Misconception |
Reality |
|---|---|
Controls where media flows |
Location Hint has no effect on media routing |
Guarantees media or signalling stays within a specific region |
No regional guarantee is provided |
Replaces or interacts with Media Mesh |
They operate on completely separate layers |
Acts as a compliance or data residency tool |
Not intended for data residency — use RMZ for media geographic control |
Documentation note: The Regional Media Zones guide states: "In addition to restricting media traffic, you can use the EU Proxy feature to restrict non-media traffic to use servers within the European Union." Location Hint is unrelated to this capability.
Session Control vs. Media Routing — Side by Side
Aspect |
Session Control (Signalling) |
Media Routing (SFU) |
|---|---|---|
What it manages |
Session state, participant events, signalling |
Audio and video streams |
Placement controlled by |
Platform availability + first participant's IP or Location Hint |
Media Mesh (automatic, always on) |
Scope |
One server per session |
One SFU per participant, independently assigned |
Geographic guarantee |
No |
No (use RMZ for guarantees) |
Cost |
Free |
Free |
Best Practices
Always pass a Location Hint when you know where the majority of your participants will be joining from — it is free and takes a single parameter.
Use a representative IP address from your primary audience's region, not your server's IP, unless your server is co-located with your users.
Location Hint is still recommended even when Media Mesh is enabled, since it optimises the signalling layer independently.
If you need strict geographic control over both signalling and media, use RMZ — not Location Hint.
Summary
Scenario |
Session Control Server Placement |
|---|---|
No Location Hint |
Platform default — based on availability and the first participant's IP address |
Location Hint provided |
Closest datacenter to the provided IP — best effort |
RMZ enabled |
Strictly within the configured RMZ region — hard boundary |
Articles in this section
- How Location Hint works ?
- Migrating Video REST API from OpenTok to Unified
- Video Client SDK Changes from OpenTok to Unified
- How to Migrate from OpenTok Server SDK to Unified Server SDK
- Credential Differences Between OpenTok and Unified Environments
- In which Regional Media Zones can I use Experience Composer?
- How do I monitor Video API call quality in real-time?
- JWT Tokens in the TokBox and Unified Environments
- Android SDK 2.28.2 error when using the application context
- What happens if your session lasts more than 8 hours?