Unaffiliated

Home Documentation & Help
Steamworks Documentation
IGameNotificationsService Interface
This is the interface used to interact with Game Notifications.

NOTE: This is a Service interface, methods in this interface should be called with the input_json parameter.

For more info on how to use the Steamworks Web API please see the Web API Overview.

CreateSession

POST https://partner.steam-api.com/IGameNotificationsService/CreateSession/v1/
NameTypeRequiredDescription
keystringSteamworks Web API publisher authentication key.
appiduint32The App ID to create the session for.
contextuint64Game-specified context value the game can use to associate the session with some object on their backend.
title{message}The title of the session to be displayed within each user's list of sessions.
users{message}The initial state of all users in the session.
steamiduint64(Optional) Steam ID to make the request on behalf of -- if specified, the user must be in the session and all users being added to the session must be friends with the user.

Creates a brand new async session with the players specified in the request.

The unique session id returned in this API call should be stored with the game session state of the game, as it will be used to reference other calls in the Game Notifications API

NOTE: This call requires a publisher API key to use this method. As such this API MUST be called from a secure server, and can never be used directly by clients!

Example Response:
{ "response": { "sessionid": "10" } }

Calling Example:
{ "context": "31415926" "title": { "token": "#MyToken", "variables": [ { "key": "username", "value": "SteamUser" } ] }, "users": [ { "steamid": "76561197960265729", "state": "waiting", "title": { "token": "#TitleToken", "variables": [ { "key": "username", "value": "Bob" } { "key": "level", "value": "1" } ] }, "message": { "token": "#StatusMessageToken", "variables": [ { "key": "city", "value": "Bellevue" } ] } } ] }

UpdateSession

POST https://partner.steam-api.com/IGameNotificationsService/UpdateSession/v1/
NameTypeRequiredDescription
keystringSteamworks Web API publisher authentication key.
sessioniduint64The sessionid to update.
appiduint32The App ID of the session to update.
title{message}(Optional) The new title of the session. If not specified, the title will not be changed.
users{message}(Optional) A list of users whose state will be updated to reflect the given state. If the users are not already in the session, they will be added to it.
steamiduint64(Optional) Steam ID to make the request on behalf of -- if specified, the user must be in the session.

Update a game session whenever the state of the game changes.

Be sure to update the state of each user accordingly, as what is sent here will be reflected in user notifications for all users in the game. Any users that were in the session that are not specified will be removed from the session, and any newly specified users will be added to the session. You must send the complete state of the session -- all previous state will be replaced by the newly specified state.

NOTE: This call requires a publisher API key to use this method. As such this API MUST be called from a secure server, and can never be used directly by clients!

Example Response:
{ "response": { } }

Calling Example:
{ "sessionid": "1234", "title": { "token": "#MyToken", "variables": [ { "key": "username", "value": "SteamUser" } ] }, "users": [ { "steamid": "76561197960265729", "state": "waiting", "title": { "token": "#TitleToken", "variables": [ { "key": "username", "value": "Bob" } { "key": "level", "value": "1" } ] }, "message": { "token": "#StatusMessageToken", "variables": [ { "key": "city", "value": "Bellevue" } ] } }, { "steamid": "76561197960265730", "state": "waiting", "title": { "token": "#TitleToken", "variables": [ { "key": "username", "value": "Greg" } { "key": "level", "value": "2" } ] }, "message": { "token": "#StatusMessageToken", "variables": [ { "key": "city", "value": "Seattle" } ] } } ] }

EnumerateSessionsForApp

GET https://partner.steam-api.com/IGameNotificationsService/EnumerateSessionsForApp/v1/
NameTypeRequiredDescription
keystringSteamworks Web API publisher authentication key.
appiduint32The sessionid to request details for. Optional. If not specified, all the user's sessions will be returned.
steamiduint64The user whose sessions are to be enumerated.
include_all_user_messagesbool(Optional) Set whether the message for all users should be included. Defaults to false.
include_auth_user_messagebool(Optional) Set whether the message for the authenticated user should be included. Defaults to false.
languagestring(Optional) Language to localize the text in.

This returns a list of sessions that a Steam ID is part of.

The optional bools will return further details about each session if set.

NOTE: This call requires a publisher API key to use this method. As such this API MUST be called from a secure server, and can never be used directly by clients!

Example Response:
{ "response": { [ { "sessionid": "123", "appid": "100", "title": { "token": "#TitleToken", "variables": [ { "key": "keyName", "value": "keyValue" } ] }, "time_created": "100000", // Unix time "time_updated": "200000", //Unix time "user_status": [ { "steamid": "76561197960265729", "state": "waiting", "title": { "token": "#TitleToken", "variables": [ { "key": "username", "value": "Bob" } { "key": "level", "value": "1" } ] }, "message": { "token": "#StatusMessageToken", "variables": [ { "key": "city", "value": "Bellevue" } ] } }, { "steamid": "76561197960265730", "state": "waiting", "title": { "token": "#TitleToken", "variables": [ { "key": "username", "value": "Greg" } { "key": "level", "value": "2" } ] }, "message": { "token": "#StatusMessageToken", "variables": [ { "key": "city", "value": "Seattle" } ] } } ] } }

Calling Example:
{ "steamid": "76561197960265729", "include_all_user_messages": "0", "include_auth_user_message": "1" }

GetSessionDetailsForApp

GET https://partner.steam-api.com/IGameNotificationsService/GetSessionDetailsForApp/v1/
NameTypeRequiredDescription
keystringSteamworks Web API publisher authentication key.
sessions{message}The session(s) to receive the details for
appiduint32The appid for the sessions.
languagestringLanguage to localize the text in.

Returns details about specific session(s).

NOTE: This call requires a publisher API key to use this method. As such this API MUST be called from a secure server, and can never be used directly by clients!

Example Response:
{ "response": { [ { "sessionid": "12", "appid": "100", "title": { "token": "#TitleToken", "variables": [ { "key": "keyName", "value": "keyValue" } ] }, "time_created": "100000", // Unix time "time_updated": "200000", //Unix time "user_status": [ { "steamid": "76561197960265729", "state": "waiting", "title": { "token": "#TitleToken", "variables": [ { "key": "username", "value": "Bob" } { "key": "level", "value": "1" } ] }, "message": { "token": "#StatusMessageToken", "variables": [ { "key": "city", "value": "Bellevue" } ] } }, { "steamid": "76561197960265730", "state": "waiting", "title": { "token": "#TitleToken", "variables": [ { "key": "username", "value": "Greg" } { "key": "level", "value": "2" } ] }, "message": { "token": "#StatusMessageToken", "variables": [ { "key": "city", "value": "Seattle" } ] } } ] } }

Calling Example:
{ "sessions": [ { "sessionid": "12", "include_all_user_messages": "0" }, { "sessionid": "13", "include_all_user_messages": "0" } ] }

RequestNotifications

POST https://partner.steam-api.com/IGameNotificationsService/RequestNotifications/v1/
NameTypeRequiredDescription
keystringSteamworks Web API publisher authentication key.
steamiduint64The Steam ID to request notifications for.
appiduint32The App ID to request notifications for.

Requests that a user receive game notifications for an app.

Whenever a user starts a game that requires game notifications, the server must make a RequestNotifications call for the signed in user. This will register your game to use offline notifications with the user by asking the user to opt into game notifications for your specific game. Make this call, at most, once per game launch. Subsequent calls will not ask the user to opt in if the user has decided to opt out.

NOTE: This call requires a publisher API key to use this method. As such this API MUST be called from a secure server, and can never be used directly by clients!

Example Response:
{ "response": { } }

Calling Example:
{ "steamid": "76561197960265729", "appid": 480 }

DeleteSession

POST https://partner.steam-api.com/IGameNotificationsService/DeleteSession/v1/
NameTypeRequiredDescription
keystringSteamworks Web API publisher authentication key.
sessioniduint64The sessionid to delete.
appiduint32The App ID of the session to delete.
steamiduint64(Optional) Steam ID to make the request on behalf of -- if specified, the user must be in the session.

Delete an active async game session. This will remove all notifications to any user that is part of the game session.

NOTE: This call requires a publisher API key to use this method. As such this API MUST be called from a secure server, and can never be used directly by clients!

Example Response:
{ "response": { } }

Calling Example:
{ "sessionid": "10" }

DeleteSessionBatch

POST https://partner.steam-api.com/IGameNotificationsService/DeleteSessionBatch/v1/
NameTypeRequiredDescription
keystringSteamworks Web API publisher authentication key.
sessioniduint64The sessionid to delete.
appiduint32The appid of the session to delete.

Deletes a batch of async game sessions

NOTE: This call requires a publisher API key to use this method. As such this API MUST be called from a secure server, and can never be used directly by clients!