API
Github Repository: https://github.com/googleforgames/open-match2
OpenMatchService gRPC API
The OpenMatchService is a gRPC-based API designed for managing matchmaking tickets, invoking matchmaking functions, and handling ticket assignments in a matchmaking system. The service provides several remote methods (RPCs) to interact with the matchmaking system, including creating tickets, activating/deactivating tickets, and invoking matchmaking functions.
API Methods
The OpenMatchService API exposes the following methods:
- CreateTicket: Creates a new matchmaking ticket and returns its ID.
- DeactivateTickets: Deactivates a list of tickets, removing them from matchmaking.
- ActivateTickets: Activates a list of tickets, making them eligible for matchmaking.
- InvokeMatchmakingFunctions: Invokes external matchmaking functions and processes the results.
- CreateAssignments (Deprecated): Creates assignments for a list of tickets.
- WatchAssignments (Deprecated): Streams the assignment status for requested tickets.
CreateTicket
RPC Name: CreateTicket
Request: CreateTicketRequest
Response: CreateTicketResponse
Description: Creates a new ticket in the system, marking it as “inactive” at creation. This ticket is placed in state storage and will expire after the configured OM_TICKET_TTL_SECS time-to-live. Tickets initially do not appear in matchmaking pools until they are activated using the ActivateTickets RPC.
Example
Request:
{
"ticket": {
"player_id": "player_id",
"metadata": {
"skill_level": "beginner",
"region": "NA"
}
}
}
Response:
{ "ticket_id": "abcdef12345" }
ActivateTickets
RPC Name: ActivateTickets
Request: ActivateTicketsRequest
Response: Empty
Description: Activates a list of ticket IDs, making them eligible to be placed in matchmaking pools.
Example
Request:
{ "ticket_ids": ["abcdef12345", "ghijk67890"] }
DeactivateTickets
RPC Name: DeactivateTickets
Request: DeactivateTicketsRequest
Response: Empty
Description: Activates a list of ticket IDs, making them eligible to be placed in matchmaking pools.
Example
Request:
{ "ticket_ids": ["abcdef12345", "ghijk67890"] }
InvokeMatchmakingFunctions
RPC Name: InvokeMatchmakingFunctions
Request: MmfRequest
Response: stream StreamedMmfResponse
Description: This RPC is the core of matchmaking. It takes a match profile, processes the tickets based on pool filters, and invokes external matchmaking functions to return valid matchmaking results.
Example
Request:
{
"profile": {
"name": "1v1",
"pools": {
"all": {
"name": "everyone"
}
}
},
"mmfs": [
{
"host": "http://mmf.default.svc.cluster.local",
"port": 50502,
"type": "GRPC"
}
]
}
Response:
[
{
"match": {
"id": "profile-1v1-time-2025-06-03T20:06:57.10-num-0",
"rosters": {
"everyone": {
"name": "1v1",
"tickets": [
{
"id": "1748981212557-0",
"expirationTime": "2025-06-03T20:16:52.440304094Z",
"attributes": {
"creationTime": "2025-06-03T20:06:52.440303651Z"
}
},
{
"id": "1748981214061-0",
"expirationTime": "2025-06-03T20:16:53.995424380Z",
"attributes": {
"creationTime": "2025-06-03T20:06:53.995424041Z"
}
}
]
}
}
}
}
]
WatchAssignments (Deprecated)
RPC Name: WatchAssignments Request: WatchAssignmentsRequest Response: stream StreamedWatchAssignmentsResponse
Description: Streams assignments for each ticket ID requested, as long as they exist before the specified timeout. This RPC is designed for situations where clients need to continuously monitor the status of assignments for tickets, such as when you want to know when a player has been assigned to a server or a match.
Example
Request:
{
"ticket_ids": ["abcdef12345", "ghijk67890"]
}
Response:
[
{
"ticket_id": "abcdef12345",
"assignment_details": {
"server_id": "server_1",
"match_id": "match_12345"
}
},
{
"ticket_id": "ghijk67890",
"assignment_details": {
"server_id": "server_2",
"match_id": "match_12346"
}
}
]
CreateAssignments (Deprecated)
RPC Name: CreateAssignments Request: CreateAssignmentsRequest Response: Empty
Description: Creates assignments that contain match information for tickets with matches assigned.
Example
Request:
{
"assignment_roster": [
{
"ticket_id": "abcdef12345",
"assignment_details": {
"server_id": "server_1",
"match_id": "match_12345"
}
}
]
}
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.
Last modified June 17, 2025