Loading...

Game events API

Please read the overwolf.games.events documentation page to learn how to use Overwolf game events.

Sample Apps

• OVERWATCH game events sample app.

Available Features

• gep_internal
• game_info
• match_info
• kill
• assist
• death
• roster

Game event status

It is highly recommended to communicate errors and warnings to app users.

Check the current game event status here. Alternately, you can easily check that status from your app itself, using our API.

gep_internal

Info Updates

key	Category	Values	Notes	Since GEP Ver.
gep_internal	gep_internal	Local + Public version number	See notes	229.0

gep_internal note

Data Example:

{"info":{"gep_internal":{"version_info":"{"local_version":"157.0.1","public_version":"157.0.1","is_updated":true}"}},"feature":"gep_internal"}

game_info

Info Updates

key	Category	Values	Notes	Since GEP Ver.
game_state	game_info	The current state of the game.	See notes	229.0
game_mode	game_info	Currently played game-mode.	See notes	229.0
battle_tag	game_info	Player's battelnet tag	See notes	229.2
game_type	match_info	The type of the current played game	See notes	252.0
game_queue_type	match_info	The type of the current queue	See notes	256.1
party_player_count	game_info	Count how many players are in the party	See notes	261.0

game_state note:

List of possible values:

• loading_screen_start
• game_loaded
• match_in_progress
• match_ended
• role_select_screen_start
• role_select_screen_end

Data Example:

{"info":{"game_info":{"game_state":"loading_screen_start"}},"feature":"game_info"}

game_mode note

Full list of game-modes:

• 0003 = "Junkensteins Revenge"
• 0007 = "Ctf"
• 0008 = "Meis Snowball Offensive"
• 0009 = "Elimination"
• 0015 = "Uprising"
• 0016 = "Skirmish"
• 0020 = "Assault"
• 0021 = "Escort"
• 0022 = "Hybrid"
• 224 = "Clash"
• 0023 = "Control"
• 0025 = "Tutorial"
• 0026 = "Uprising All Heroes"
• 0029 = "Team Deathmatch"
• 0030 = "Deathmatch"
• 0032 = "Lucioball"
• 0037 = "Retribution"
• 0041 = "Yeti Hunter"
• 0042 = "Halloween Holdout Endless"
• 0061 = "Calypso Heromode"
• 0066 = "Story Missions"
• 0067 = "Storm Rising"
• 0074 = "Survivor"
• 0089 = "Snowball Deathmatch"
• 0109 = "Flashpoint"
• 0090 = "Practice Range"
• 0112 = "Bounty Hunter"
• 0165 = "Hero Mastery - Solo"
• 0186 = "Hero Mastery CO-OP"
• 227 = "Junkenstein's Lab"
• 235 = "Overwatch Classic: Assault"
• 236 = "Overwatch Classic: Escort"
• 237 = "Overwatch Classic: Hybrid"
• 238 = "Overwatch Classic: Control"
• 253 = "Kingmaker: Escort"
• 254 = "Kingmaker: Control"
• 255 = "Kingmaker: Push"
• 256 = "Kingmaker: Hybrid"
• 257 = "Kingmaker: Flashpoint"
• 258 = "'Kingmaker: Clash"

Data Example:

{"info":{"game_info":{"game_mode":"16"}},"feature":"game_info"}

Note that on the response the leading zeros are removed ("0030" => "30")

battle_tag note

Data Example:

{"feature":"game_info","category":"game_info","key":"battle_tag","value":"OverTheTop#2100"}

game_type note:

List of possible values:

• UNKNOWN
• UNRANKED
• CUSTOM_GAME
• PRACTICE
• ARCADE
• TUTORIAL
• SKIRMISH
• VS_AI
• DEATHMATCH
• RANKED
• HERO_MASTERY
• HERO_MASTERY_SOLO

Data Example:

{"feature":"game_info","category":"match_info","key":"game_type","value":"SKIRMISH"}

game_queue_type note:

possible game_queue_type values:

• OPEN_QUEUE
• ROLE_QUEUE

Data Example:

{"feature":"game_info","category":"match_info","key":"game_queue_type","value":"OPEN_QUEUE"}

party_player_count note:

Data Example:

{"feature": "game_info", "category": "game_info", "key": "party_player_count", "data": "2"}

match_info

Info Updates

key	Category	Values	Notes	Since Version
map	match_info	Name of currently played map.	See notes	229.0
pseudo_match_id	match_info	Unique mtch_id	See notes	237.0
match_outcome	match_info	Outcome of the current match	See notes	250.1
round_outcome	match_info	Outcome of the current round	See notes	305.0
match_id	match_info	The ID of the current match	See notes	305.0

map note

Important to note some values that are still unknown. Most of them are listed down here.

Possible map values:

• 91 = "Temple of Anubis"
• 212 = "King's Row"
• 357 = "Hanamura"
• 388 = "Watchpoint: Gibraltar"
• 468 = "Numbani"
• 475 = "Volskaya Industries"
• 687 = "Hollywood"
• 707 = "Dorado"
• 1207 = "Nepal"
• 1467 = "Route 66"
• 1633 = "Tutorial"
• 1634 = "Lijiang Tower"
• 1645 = "Ilios"
• 1672 = "Practice Range"
• 1677 = "Eichenwalde"
• 1694 = "Oasis"
• 1707 = "Hollywood (Halloween)"
• 1713 = "King's Row (Winter)"
• 1715 = "Estádio das Rãs"
• 1717 = "Hanamura (Winter)"
• 1719 = "Lijiang Tower (Lunar New Year)"
• 1735 = "VPP Green Room"
• 1737 = "Junkenstein's Revenge"
• 1745 = "Ecopoint: Antarctica"
• 1747 = "Horizon Lunar Colony"
• 1797 = "Necropolis"
• 1804 = "Black Forest"
• 1805 = "Ecopoint: Antarctica (Winter)"
• 1809 = "Lijiang Garden (Lunar New Year)"
• 1810 = "Lijiang Night Market (Lunar New Year)"
• 1815 = "Nepal Sanctum"
• 1818 = "Lijiang Control Center (Lunar New Year)"
• 1820 = "Castillo"
• 1846 = "Nepal Village"
• 1848 = "Nepal Shrine"
• 1850 = "Ilios Well"
• 1853 = "Ilios Lighthouse"
• 1854 = "Ilios Ruins"
• 1860 = "Lijiang Control Center"
• 1861 = "Lijiang Garden"
• 1862 = "Lijiang Night Market"
• 1866 = "Oasis City Center"
• 1868 = "Oasis Gardens"
• 1869 = "Oasis University"
• 1878 = "Junkertown"
• 1886 = "Blizzard World"
• 1953 = "Ayutthaya"
• 1956 = "Château Guillard"
• 2018 = "Busan"
• 2036 = "Eichenwalde (Halloween)"
• 2039 = "Black Forest (Winter)"
• 2045 = "Nepal Village (Winter)"
• 2087 = "Circuit Royal"
• 2102 = "Château Guillard (Halloween)"
• 2161 = "Rialto"
• 2192 = "Petra"
• 2193 = "Paris"
• 2360 = "Paraíso"
• 2628 = "Havana"
• 2651 = "Blizzard World (Winter)"
• 2682 = "Busan Sanctuary (Lunar New Year)"
• 2694 = "Busan Downtown (Lunar New Year)"
• 2795 = "New Queen Street"
• 2812 = "Rio De Janeiro"
• 2868 = "Colosseo"
• 2892 = "Midtown"
• 3008 = "Toronto"
• 3030 = "Gothenburg"
• 3136 = "Workshop Island"
• 3140 = "Workshop Expanse"
• 3144 = "Workshop Chamber"
• 3205 = "Shambali Monastery"
• 3280 = "Workshop Expanse (Night)"
• 3281 = "Workshop Island (Night)"
• 3283 = "Kanezaka"
• 3287 = "Malevento"
• 3292 = "Busan Stadium"
• 3307 = "Sydney Harbour Arena"
• 3314 = "Antarctic Peninsula"
• 3390 = "Suravasa"
• 3404 = "Workshop Green Screen"
• 3411 = "Esperança"
• 3603 = "New Junk City"
• 3762 = "Runasapi"
• 3776 = "Samoa"
• 3893 = "Aatlis"
• 4120 = "Underworld"
• 4310 = "Antarctic Peninsula"
• 4392 = "Sanctuary"
• 4439 = "Hanaoka"
• 4448 = "Throne of Anubis"
• 4622 = "Watchpoint: Gibraltar (Talon)"
• 4695 = "Thames District"
• 4698 = "Gogadoro"
• 4702 = "Place Lacroix"
• 4704 = "Redwood Dam"
• 4721 = "Powder Keg Mine"
• 4724 = "Serenza"
• 4731 = "Ilios - Ruins"
• 4735 = "Oasis - Gardens"
• 4778 = "Arena Victoriae"
• 4784 = "Esperança"
• 4789 = "Throne of Anubis"
• 4790 = "Hanaoka"
• 4791 = "Colosseo"
• 4849 = "Nepal - Shrine"
• 4949 = "Samoa"
• 4981 = "Wuxing University - Water College"
• 5000 = "Busan - Sanctuary"
• 5195 = "Lijiang Tower - Night Market"

Data Example:

{"info":{"match_info":{"map":"3603"}},"feature":"match_info"}

Note that in the response the leading zeros are removed ("0030" => "30")

pseudo_match_id note

This is an Overwolf-generated code, unrelated to the game.

Data Example:

{"info":{"match_info":{"pseudo_match_id":"5a7e3729-993c-414d-8e3f-592faeef81e7"}},"feature":"match_info"}

match_outcome note

Possible values:

• victory
• defeat

Data Example:

{"info":{"match_info":{"match_outcome":"victory"}},"feature":"match_info"}

round_outcome note

Possible values:

• victory
• defeat

Data Example:

Only works for Stadium mode

{"info":{"match_info":{"round_outcome":"victory"}},"feature":"match_info"}

match_id note

Data Example:

{"info":{"match_info":{"match_id":"602871308"}},"feature":"match_info"}

Events

Event	Event Data	Fired When (announcement)	Notes	Since GEP Ver.
match_start	null	Match started.	See notes	229.0
match_end	null	Match ended.	See notes	229.0
round_start	null	Round started.	See notes	252.0
round_end	null	Round ended.	See notes	252.0
respawn	null	The local player respawn.	See notes	258.0
revive	null	The local player revive.	See notes	258.0
kill_feed	See data below	Anytime any player dies or revive in the match.	See notes	277.0
game_exit	null	The player exit the game or exit to desktop	See notes	312.0

match_start note

Data Example:

{"name":"match_start","data":""}

match_end note

Data Example:

{"name":"match_end","data":""}

round_start note

Data Example:

{"name":"round_start","data":""}

round_end note

Data Example:

{"name":"round_end","data":""}

respawn note

Data Example:

{"name":"respawn","data":null}

revive note

Data Example:

{"name":"revive","data":null}

kill_feed note

List of possible values:

• attacker - attacker name
• victim - victim name
• is_attacker_teammate - boolean value if the atacker hero is a teammate
• is_victim_teammate - boolean value if the victim hero is a teammate
• attacker_hero_id - id of atacker hero
• victim_hero_id - id of victim hero
• supporter - supporter name
• revived - revived name
• is_supporter_teammate - boolean value if the supporter hero is a teammate
• is_revived_teammate - boolean value if the revived hero is a teammate
• revived_hero_id - id of revived hero
• supporter_hero_id - id of supporter hero
• attacker_hero_name - name of attacker hero
• victim_hero_name - name of victim hero
• supporter_hero_name - name of supporter hero
• revived_hero_name - name of revived hero

Data Example:

["events": {"name":  "{\"attacker\":\"brandy\",\"victim\":\"SpectralSoul\",\"is_attacker_teammate\":false,\"is_victim_teammate\":false,\"attacker_hero_id\":41,\"victim_hero_id\":492,\"supporter\":\"\",\"revived\":\"\",\"is_supporter_teammate\":false,\"is_revived_teammate\":false,\"supporter_hero_id\":null,\"revived_hero_id\":null,\"attacker_hero_name\":\"GENJI\",\"victim_hero_name\":\"SOJOURN\",\"supporter_hero_name\":null,\"revived_hero_name\":null}"}]

game_exit note

Data Example:

{"name":"game_exit","data":""}

kill

Info Updates

key	Category	Values	Notes	Since GEP Ver.
eliminations	kill	Total amount of eliminations.	See notes	229.0

eliminations note

Data Example:

{"info":{"kill":{"eliminations":"6"}},"feature":"kill"}

objective_kills note

Data Example:

{"info":{"kill":{"objective_kills":"2"}},"feature":"kill"}

Events

Event	Event Data	Fired When (announcement)	Notes	Since GEP Ver.
elimination	Integer	Elimination is performed.	See notes	229.0

elimination note

The event includes the total amount of eliminations performed in the match.

Data Example:

{"name":"elimination","data":"8"}

death

Info Updates

key	Category	Values	Notes	Since GEP Ver.
deaths	death	Total amount of deaths.	See notes	229.0

death note

Data Example:

{"info":{"death":{"deaths":"5"}},"feature":"death"}

Events

Event	Event Data	Fired When (announcement)	Notes	Since GEP Ver.
death	Integer	Death has occurred.	See notes	229.0

death note

The event includes the total amount of deaths performed in the match.

Data Example:

{"name":"death","data":"2"}

assist

Info Updates

key	Category	Values	Notes	Since GEP Ver.
assists	death	Total amount of assists.	See notes	229.0

assist note

Data Example:

{"info":{"assist":{"assist":"5"}},"feature":"assist"}

Events

Event	Event Data	Fired When (announcement)	Notes	Since GEP Ver.
assist	Integer	Assist has occurred.	See notes	229.0

assist note

The event includes the total amount of assists performed in the match.

Data Example:

{"name":"assist","data":"2"}

roster

Info Updates

key	Category	Values	Notes	Since GEP Ver.
roster_XX	roster	Data about the roter	See [notes](#roster_XX -note)	249.0

*roster_XX * note

List of values:

• player_name - the player's full name
• battlenet_tag - the battle net tag
• is_local - is the player the local player true/false
• is_teammate - is the player one of your teammates true/false
• hero_name - the name of the selected hero
• hero_role - the role of the selected hero
• team - the player's team 0/1
• kills / deaths / assists - the total number of kills/deaths/assists
• damage - the total damage
• healed - the total healed
• mitigated - the total mitigated
• hero_id - the id of the hero (see hero_id note)

caution

As for version 249.1.0 hero_name and hero_role will be available for the local player team only We will add them to the other team in the next GEP release

Data Example:

{"feature":"roster","category":"roster","key":"roster_0","value":"{\"player_name\":\"CHARLOGNE\",\"is_local\":false,\"hero_name\":\"LUCIO\",\"hero_role\":\"SUPPORT\",\"team\":0,\"kills\":18,\"deaths\":9,\"damage\":5318.73,\"assists\":21,\"healed\":12641.1,\"mitigated\":1708.42,\"battlenet_tag\":\"charlogne#2351\",\"hero_id\":121,\"is_teammate\":false}"}

hero_id note

Possible hero_id values (also used for attacker_hero_id, victim_hero_id, supporter_hero_id and revived_hero_id in the kill_feed event):

• 0 = "UNKNOWN"
• 2 = "REAPER"
• 3 = "TRACER"
• 4 = "MERCY"
• 5 = "HANZO"
• 6 = "TORBJORN"
• 7 = "REINHARDT"
• 8 = "PHARAH"
• 9 = "WINSTON"
• 10 = "WIDOWMAKER"
• 21 = "BASTION"
• 22 = "SYMMETRA"
• 32 = "ZENYATTA"
• 41 = "GENJI"
• 64 = "ROADHOG"
• 66 = "CASSIDY"
• 101 = "JUNKRAT"
• 104 = "ZARYA"
• 110 = "SOLDIER76"
• 121 = "LUCIO"
• 122 = "DVA"
• 221 = "MEI"
• 302 = "SOMBRA"
• 303 = "DOOMFIST"
• 315 = "ANA"
• 318 = "ORISA"
• 405 = "BRIGITTE"
• 418 = "MOIRA"
• 458 = "WRECKINGBALL"
• 492 = "SOJOURN"
• 512 = "ASHE"
• 518 = "ECHO"
• 545 = "BAPTISTE"
• 561 = "KIRIKO"
• 566 = "JUNKERQUEEN"
• 571 = "SIGMA"
• 653 = "RAMATTRA"
• 657 = "LIFEWEAVER"
• 778 = "MAUGA"
• 796 = "ILLARI"
• 810 = "FREJA"
• 811 = "VENTURE"
• 866 = "HAZARD"
• 869 = "JUNO"
• 963 = "WUYANG"
• 1138 = "VENDETTA"
• 1220 = "DOMINA"
• 1234 = "SIERRA"
• 1240 = "EMRE"
• 1245 = "ANRAN"
• 1251 = "MIZUKI"
• 1302 = "JETPACKCAT"
• 1324 = "SHION"
• 1346 = "DMON"
• 1392 = "DOCTRINE"
• 4855 = "HANZO DRAGONSTRIKE"
• 4881 = "TRACER PULSE BOMB"
• 9877 = "ZARYA GRAVITON SURGE"
• 20076 = "MEI BLIZZARD"
• 20139 = "BAPTISTE IMMORTALITY FIELD"
• 36428 = "JUNKRAT RIP TIRE"
• 114114 = "ASHE BOB"
• 262861 = "ILLARI CAPTIVE SUN"
• 284666 = "TORBJORN TURRET"
• 284669 = "ILLARI HEALING PYLON"
• 284671 = "DVA MECH"
• 284792 = "LIFEWEAVER TREE OF LIFE"

Events status

Loading...