Skip to main content

Player vs player session


Endpoint API definition
Authorization through the X-Api-Key header containing your API key is required.

With the API, you can create a game session that returns embeddable URLs that can be used by your application to connect two remote players.


The POST Create an embeddable game session endpoint allows you to specify the configuration that fit the needs of your App.

gameTyperequiredEnum (TicTacToe, Connect4 , Gomoku, Battleships, Chess)
languagerequiredEnum (en, fr, es, vi, ru, pt-br, cz, id, de)
inactivityTimeoutoptionalNumberTime per turn in seconds. How much time each player has to make a move. Set to 0 if you want infinite time per turn.
timerTimeoutoptionalNumberTotal time per player in seconds. How much time each player receives to complete a single game. Set to 0 if you want infinite time per player.
boardSizeoptionalStringThe size of the board, appliable only for Tic-Tac-Toe (3x3, 5x5) and Connect 4 (7x6, 8x7, 8x8, 9x7, 9x9). If no boardSize is specified, or if the value is wrong, it fallbacks to the classic size.
maxGamesoptionalNumberMaximum number of games per session. If not specified, the game session has unlimited games. We recommend setting it to odd values (1, 3, 5) to try to have a winner.

Keep in mind that the timerTimeout parameter should always be greater than the inactivityTimeout.

Sample payload

"gameType": "TicTacToe",
"language": "en",
"inactivityTimeout": 30,
"timerTimeout": 60

Sample response

"uid": "wdnH6gXc1",
"playUrl": "",
"watchUrl": ""

The playUrl field contains an embeddable URL that can be integrated into an iframe for a user to play.
The watchUrl field contains an embeddable URL that can be integrated into an iframe for a user to watch the game as a spectator. The uid field contains the identifier for the game session. It can be combined with Webhooks to update your system with the game score.


To have a better understanding of the flow, head up to the Getting started section where you can test our API with a short and practical example (5 minutes ⏱).

iFrame integration

When you create pvp game session, your receive playUrl as a response. This URL can be embedded in an iframe to connect two players.
On your frontend application, you need to create an iframe and set the src attribute to the playUrl value, with a few extra parameters.

iframe query parameters

Query parameterSample valueRequiredDescription
usernameJohn DoeyesThis is used as a display name on papergames.
externalUserIdJF_001noThis field is useful if you listen to webhook events. It will be populated on the payload. If you don't use webhooks, you can skip this parameter.

Exaple of an iframe with the query parameters:

<iframe src=""></iframe>

Timing considerations

Games like Tic-Tac-Toe have a completion average of 15 seconds. Chess completion average is 10 to 15 minutes. Ensure you set the timing options to a reasonable value for average players to feel comfortable. If you're unsure about the timing values, you can follow the recommendations below.

Tic Tac Toe30120
Connect 440240

If you don't want to stress out the players with timers, simply set both inactivityTimeout and timerTimeout to 0.

Game session expiration

The game sessions don't expire automatically. Therefore, you can create one and start it five days later. They expire only under the conditions below.

  • Player1 joins and leaves (e.g., when the iframe is destroyed from the DOM), without starting a game with Player1
  • Player1 and Player2 are matched together. As soon as one of them leaves the game (e.g. when the iframe is destroyed from the DOM)