Create, configure, and edit session templates

Last updated on October 19, 2026

Overview

AccelByte Gaming Services (AGS) Session allows you to implement sessions into your game. A session is a critical component for many games, particularly those with online multiplayer, as it allows players to connect with each other.

Session templates in AGS enable game developers to configure a session's joinability, allowed players, leader elections, and other options. This article covers creating and configuring session templates in the AGS Admin Portal or with the AGS CLI.

Prerequisites

• A familiarity with AGS Matchmaking.
• Access to the AGS Admin Portal.

• To follow the AGS CLI steps, you must have installed the AGS CLI and signed in with an account that has access to these features. See Install and sign in. The examples use a Bash shell.

Create and configure a session template

Admin Portal

1. In the Admin Portal, go to your desired namespace.

2. On the sidebar, go to Multiplayer > Matchmaking > Session Configuration. Under the Session Template tab, click + Add Session Template.

3. In the General section of the Create Session Template page, fill in the required information as desired using the following guide:

   • Session Template Name: type in a name for the session template.
   • Min Players: set the minimum number of players allowed in the session.
   • Max Players: set the maximum number of players allowed in the session.
   • Player Active Session Limit: set the maximum number of concurrent sessions are allowed per player (use -1 for unlimited).
   • Joinability: select the joinability setting.
   • Invite Timeout: set the time limit (in seconds) before a session invite times out. For example, if this is set to 60, the session will drop a player that was in the session but is disconnected from AGS Lobby for more than 60 seconds.
   • Inactive Timeout: set the time limit (in seconds) for how long the session will wait before timing a player out that has been disconnected from AGS Lobby and hasn't reconnected.
   • Leader Election Grace Period: set the duration (in seconds) for selecting a new leader when the current leader is disconnected. This applies to party sessions only.
   • Server: select the session type based on the connection used. If you set this to NONE and Joinability to INVITE ONLY, the session would behave like a party session and a new player can only join if they are invited.
   • Requested Regions: only appears when DS - AMS is selected as the Server. Select the regions this session can be used in.

4. Click Next. In the Additional section of the Create Session Template page, configure the options as desired using the following guide:

   • Auto-accept Session: If enabled, players will auto-accept the session invitation and join the session directly once the match is formed.
   • Enable Chat Room: If enabled, a chat room for players in the session will be provided for them to chat with each other.
   • Enable Secret Validation: If enabled, the session will generate a secret key for player validation during connection.
   • Generate Code: If enabled, the session will generate a session code.
   • Immutable Session Storage: If enabled, players in the session will be prevented from modifying the session storage.
   • Manual Set Ready for Dedicated Server (DS): If enabled, the dedicated server will be required to call a specific endpoint, signaling that the dedicated server will be ready to accept client connection for the game session.
   • Tied Teams Session Lifetime: If enabled, the lifetime of any party session within the teams will be linked to the game session.
   • Auto-leave Game Session: If enabled, the player will leave the current game session when joining a new one. This will limit the player's active game session to always one. The Player Active Session Limit will be ignored when this config is enabled.

5. Click Next. In the 3rd Party Sync section of the Create Session Template page, enable or disable the Enable session Sync as desired. Enabling this option will prompt the session to synchronize with a third-party platform.

6. Click Next to be taken to a page where you will have the option to apply Custom Attributes. Do so as desired, or leave it blank.

7. Click Next and review the Summary of your session template. If you're satisfied with its configuration, click Create and then OK on the pop-up to confirm. Your new session template will be listed on the Multiplayer > Matchmaking > Session Configuration page under the Session Template List.

AGS CLI

1. Create a JSON file with the template's settings. Any file name works. This example uses session-template.json:

   {
     "name": "<YourTemplateName>",
     "minPlayers": 2,
     "maxPlayers": 4,
     "maxActiveSessions": -1,
     "joinability": "OPEN",
     "inviteTimeout": 60,
     "inactiveTimeout": 60,
     "type": "NONE",
     "autoJoin": false,
     "textChat": false,
     "partyCodeLength": 4
   }

   The following table maps the Admin Portal fields to the request body fields. Fields you leave out get the service defaults. To see every field, run ags session templates create --skeleton.

   Admin Portal field	Request body field
   Session Template Name	name
   Min Players	minPlayers
   Max Players	maxPlayers
   Player Active Session Limit	maxActiveSessions
   Joinability	joinability: OPEN, INVITE_ONLY, CLOSED, FRIENDS_OF_MEMBERS, FRIENDS_OF_LEADER, or FRIENDS_OF_FRIENDS
   Invite Timeout	inviteTimeout
   Inactive Timeout	inactiveTimeout
   Leader Election Grace Period	leaderElectionGracePeriod
   Server	type and dsSource (see the note below)
   Requested Regions	requestedRegions
   Auto-accept Session	autoJoin
   Enable Chat Room	textChat
   Enable Secret Validation	enableSecret
   Generate Code	disableCodeGeneration (the opposite value: false generates a code)
   Immutable Session Storage	immutableStorage
   Manual Set Ready for Dedicated Server (DS)	dsManualSetReady
   Tied Teams Session Lifetime	tieTeamsSessionLifetime
   Auto-leave Game Session	autoLeaveSession
   Party Code Length	partyCodeLength (the Admin Portal sends 4; if you leave it out, the service uses 6)
   Enable Session Sync	NativeSessionSetting.ShouldSync
   Custom Attributes	attributes

   note

   The Admin Portal's Server option sets two fields:

   • NONE: set type to NONE.
   • P2P: set type to P2P.
   • DS - AMS: set type to DS and dsSource to AMS, Optionally, list default regions in requestedRegions, for example ["us-east-2"].
   • DS - Custom: set type to DS and dsSource to custom. Then set appName to the name of your Extend app, or customURLGRPC to your gRPC server's address. Also set deployment, and list at least one region in requestedRegions.

   If you set type to DS without dsSource, the template doesn't use AMS.

2. Create the template. After @, pass the path to your JSON file. Replace <YourNamespace> with your namespace.

   ags session templates create --namespace <YourNamespace> --json @session-template.json

info

When you configure the session server to use a DS (either DS-AMS or DS-Custom), the Session service requests the DS from the provider once the minimum number of players join. If the minimum player count is set to 0, the Session service requests a DS immediately after the session is created.

Edit a session template

You can make changes to session templates you created by doing the following:

Admin Portal

1. In the Admin Portal, go to your desired namespace.

2. On the sidebar, go to Multiplayer > Matchmaking > Session Configuration. Under the Session Template tab, find the template you'd like to change and click its name.

3. Make any adjustments to the session template. Once you're done, click Save and then OK on the pop-up to confirm. Your adjustments will be saved.

AGS CLI

1. Find the name of the template you want to change:

   ags session templates list --namespace <YourNamespace>

2. Save the template's current settings to a file:

   ags session templates get --namespace <YourNamespace> --name <YourTemplateName> --format json > session-template.json

3. In session-template.json, edit the values you want to change. Keep the other fields as they are. You can't change the template's name.

4. Send the file back:

   ags session templates update --namespace <YourNamespace> --name <YourTemplateName> --json @session-template.json

   warning

   The update replaces the whole template, so any field you leave out is reset, including the third-party sync settings and custom attributes. Always start from the saved file.

Delete a session template

You can delete a session template by doing the following:

Admin Portal

1. In the Admin Portal, go to your desired namespace.

2. On the sidebar, go to Multiplayer > Matchmaking > Session Configuration. Under the Session Template List tab, find the template you'd like to remove.

3. Click on the delete icon and make sure to confirm the deletion because it will impact the current active session (both game and party).

AGS CLI

1. Find the name of the template you want to delete:

   ags session templates list --namespace <YourNamespace>

2. Delete the template:

   ags session templates delete --namespace <YourNamespace> --name <YourTemplateName>

danger

By deleting the Session Template, all associated sessions (game or party) will be deactivated immediately. The users who are active in the sessions will be notified. This action cannot be undone, and the sessions will be rendered inactive. Please ensure you are aware of the potential impact on any ongoing sessions before deleting the session template.