LogoLogo
edgegap.comDashboard
  • 📘Learning Center
    • Getting Started
    • Unity Games
      • Getting Started - Servers
      • Developer Tools
    • Unreal Engine Games
      • Getting Started - Servers
      • Developer Tools
    • Matchmaking
      • Getting Started
      • Matchmaker In-Depth
      • Ping Beacons
    • Advanced Features
      • Apps and Versions
      • Deployments
      • Managed Clusters
  • API Reference
    • Dedicated Servers
    • Integration
    • Matchmaking
    • Peer to Peer
  • Release Notes
  • 📚Documentation
    • Sample Projects
      • Unity Netcodes
        • Unity NGO
        • Photon Fusion 1
        • Photon Fusion 2
        • Mirror
        • Mirror WebGL
        • Fishnet
        • Fishnet WebGL
        • Photon Bolt
      • Unreal Top-Down Sample
      • NuxtJS
      • Ruby On Rails
      • Unity Lobbies
      • Unity Matchmaker
    • Tools & Integrations
      • Container
        • What is Docker
        • Your First Docker
        • SSH in Your Container
        • External Registries
          • Docker Hub
          • AWS ECR
          • GCP GCR
          • Gitlab registry
      • Deploy from Nakama
      • EOS Lobby Integration
      • Switch From Gamelift
      • Switch From Multiplay
      • Playfab Bridge
    • Deployment
      • Endpoint Storage
        • How to Save Logs
        • Upload File to Deployment
      • Webhooks
    • Application
      • Command and Arguments
      • 1:1 Port Mapping
    • Session
      • How They Work
      • Application Version Configuration
      • Manage Request
      • Selectors Filtering
    • Fleet
      • Fleet Policy
      • Policy Filter
      • Linking Version
      • Fleet's Deployment
    • Container Registry
    • Distributed Relay
      • Matchmaker/Lobby
      • Relay Edgegap API
      • Transport Samples
    • Lobby
      • Lobby Service
      • Functions
    • Glossary
    • SLA Terms
Powered by GitBook
LogoLogo

Connect with Community

  • Discord
  • Linkedin
  • X

Read More

  • Release Notes
  • Blog
  • Enterprise
  • Legal
  • edgegap.com

© 2025 Edgegap

On this page
  • Create the Initial Request
  • Handling the Session Statuses
  • Deleting a Session
  • Basic Filtering
  • Session Webhook Call-flow

Was this helpful?

  1. Documentation
  2. Session

Manage Request

PreviousApplication Version ConfigurationNextSelectors Filtering

Last updated 2 months ago

Was this helpful?

In this section, we will show a basic example on how you can manage a session request from start to finish.

Let's say we have an application version set with Seat, four sockets, and autodeploy. You should backtrack in the session's documentation if you are unfamiliar with these terms.

Create the Initial Request

Our matchmaker has determined that players with IP addresses 1.2.3.4 and 5.6.7.8 want to play together. The matchmaker will send a request to create a session for them. You can find the full .

We do not currently have a deployment to host our session request, so Arbitrium will automatically create one for our two players.

It is not ideal to query the API repeatedly to check if the session is ready. To avoid this, you can use a , which is the recommended practice.

POST - /v1/session
{
  "app_name": "demo",
  "version_name": "v1",
  "ip_list": ["1.2.3.4", "5.6.7.8"],
  "continent": "North America",
  "webhook_url": "https://my-webhook.com/callback"
}

Handling the Session Statuses

You will receive the same body whether you choose to use the webhook or to make GET requests. The session GET body contains various status and keys, but you only need to manage the status key. The three statuses you should handle are Ready, Error, and Unprocessable.

Error and Unprocessable

If your session is in either of these two statuses, it means that we were unable to link your session to a ready deployment. As a result, you will not have a URL to connect your players. It is important that you handle these statuses within your backend. It can happen for various reasons.

  • You did not activate the autodeploy option so no deployments are available or there all at full capacity.

  • We could not deploy your application version due to bad configuration.

Ready

When your session's status is Ready, it means that it is ready for your players to connect to the deployment. You can take the connection URL in deployment ports part of the GET body.

GET - /v1/session/{session_id}
{
  "session_id": "bc4d21eaf686-S",
  "status": "Ready",
  "deployment": {
    "request_id": "628572d11014",
    "fqdn": "628572d11014.st.edgegap.net",
    "ports": {
      "80": {
        "link": "628572d11014.st.edgegap.net:32072"
      }
    }
  }
}

There is more information in the body, but we have removed what is not related to the example for clarity.

Initializing, Seeking, Waiting

These are pending statuses, meaning that they occur when we are currently analyzing which deployment should host your session or when we are currently deploying a new deployment. You don't really need to handle these statuses.

Deleting a Session

When you determine that you need to delete the session, whether because you're disconnecting the connection between the server and your players and/or the match is over, you need to send us a deletion request.

As mentioned earlier, sessions are not physical connections, and therefore, you need to handle the physical connection and disconnection of your players. These manipulations should be in sync with the creation and deletion of sessions. If you do not delete your sessions, it will result in false session socket usage, and you will end up consuming a lot more resources than needed. It's important to note that Edgegap is not able to determine when your players should be connected to the server or not, so you need to handle this on your backend.

Basic Filtering

In the next section, we will show you how you can do some advanced filtering using Selectors and tags on your deployments.

Session Webhook Call-flow

When you create a session, you can provide a webhook URL to receive updates on the session's status. This is a more efficient way to manage your sessions than polling the API.

The following sequence diagram illustrates the call-flow of a session webhook.

You can simply with a DELETE request to /v1/session/{SESSION_ID}. Your session will go into a Terminating state before it's not available anymore.

You can filter the sessions to enforce a specific location such as a country, continent, or city. You can also specify a latitude and longitude, and the deployment will be made as close as possible to that geographical point. You can see the full list of filters . This can be helpful to use in your matchmaking system.

📚
API documentation here
webhook
delete a session
here