Hearthstone Game events | Overwolf Developers

Game events API
Events status

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

Sample Apps

Hearthstone game events sample app

Available Features

gep_internal
scene_state
collection
decks
match
match-info
arena

Game events status

It is highly recommended to communicate errors and warnings to your app users. Check game event status here, or easily check game events status from your app using our API.

`gep_internal`

Info Updates

key	Category	Values	Notes	Since GEP Ver.
gep_internal	gep_internal	Local + Public version number	See notes	143.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"}

`collection`

Info Updates

key	Category	Values	Notes	Since GEP Ver.
collection	game_info	Current card collection of the local player.	See notes	117.1

collection note

The “collection” data is available as soon as the player logs into Hearthstone.
The collection is updated whenever the user adds/removes a card.

Example for cards "collection":

{ CS2_065: "{"id" : "CS2_065", "count" : "1", "premiumCount" : "0" }",
  CS1_113: "{"id" : "CS1_113", "count" : "2", "premiumCount" : "0" }",
  NEW1_011: "{"id" : "NEW1_011", "count" : "2", "premiumCount" : "0" }",
  EX1_131: "{"id" : "EX1_131", "count" : "1", "premiumCount" : "2" }",
  CS2_121: "{"id" : "CS2_121", "count" : "2", "premiumCount" : "0" }",
  …
}

"Card" structure:

{ "id" : "card_id" , "count" : "int" , "premiumCount" : "int" }

“id” – The card’s id
“count” – The number of regular cards
“premiumCount” – The number of premium (golden) cards

`scene_state`

Info Updates

key	Category	Values	Notes	Since GEP Ver.
scene_state	game_info	Current game scene.	See notes	117.1

scene_state note

Can be one of the following:

scene_startup
scene_login
scene_hub
scene_gameplay
scene_collectionmanager
scene_packs
scene_tournament
scene_friendly
scene_fatal_error
scene_draft
scene_credits
scene_reset
scene_adventure
scene_tavern_brawl

`decks`

Info Updates

key	Category	Values	Notes	Since GEP Ver.
[deck_id]	decks	The “decks” feature provides data about the currently “visible” decks.	See notes	119.1
selected_deck	selected_deck	The selected deck.	See notes	119.1
Adventure Deck	decks	The currently played deck on adventure mode.	See notes	143.0
adventure_loot_options	decks	The currently offered 3-option draft (between bosses)	See notes	143.0

deck_id note

The key is the deck's deck_id string. It is not the literal string "deck_id". See the example below.

Decks are “visible” when the local player starts a new game, during the “deck selection” screen, or when the local player enters the “My Collection” menu. The following data is being provided for each deck:

Deck name/id
Deck cards (array of cards)
Deck key

“Card” structure:

{ "id" : "card_id", "count" : "int", "premiumCount" : "int" }

“id” – The card's id
“count” – The number of regular cards
“premiumCount” – The number of premium (golden) cards

Example for a “deck_id” info-update structure:

{
  "info":{
    "decks":{
      "Mage":"{
        \"deck_id\":\"Mage\",
          \"cards\":[
            {\"id\":\"BOT_573\",\"count\":1,\"premiumCount\":0},
            {\"id\":\"CS2_024\",\"count\":2,\"premiumCount\":0},
            {\"id\":\"CS2_033\",\"count\":1,\"premiumCount\":0},
            ...
            {\"id\":\"UNG_845\",\"count\":1,\"premiumCount\":0},
            {\"id\":\"UNG_941\",\"count\":1,\"premiumCount\":0}
          ],
        \"deck_key\":\"adventure_deck\"
      }"
    }
  },
  "feature":"decks"
}

Arena Decks

Arena Decks, unlike standard decks, will be updated each time the local player chooses a card during the Arena Draft phase.

selected_deck note

The following data is provided when the local player selects a deck:

“deck_id”
“deck_name”
“class_skin” – Deck image name

Example of a “selected deck” structure:

{"feature":"decks","category":"selected_deck","key":"selected_deck","value": "{"deck_id":"706741699","deck_name":"Basic Shaman","class_skin":"Thrall" }

adventure deck note

Data Example:

{
   "info":{
      "decks":{
         "Adventure Deck":"{
                            "deck_id":"Adventure Deck",
                            "cards":[
                                      {"id":"BOT_573","count":1,"premiumCount":0},
                                      {"id":"CS2_024","count":2,"premiumCount":0},
                                      {"id":"CS2_033","count":1,"premiumCount":0},
                                      ...
                                      {"id":"UNG_845","count":1,"premiumCount":0},
                                      {"id":"UNG_941","count":1,"premiumCount":0}
                                    ],
                             "deck_key":"adventure_deck"
                           }"
           }
   },
   "feature":"decks"
}

adventure_loot_options note

Data Example:

{
   "info":{
      "decks":{
               "adventure_loot_options":"[
                                          {"deck_id":"option_a","cards":[
                                                                         {"id":"EX1_279","count":1,"premiumCount":0},
                                                                         {"id":"EX1_559","count":1,"premiumCount":0},
                                                                         {"id":"GVG_001","count":1,"premiumCount":0}
                                                                         ]
                                           },
                                          {"deck_id":"option_b","cards":[
                                                                          {"id":"AT_090","count":1,"premiumCount":0},
                                                                          {"id":"AT_099","count":1,"premiumCount":0},
                                                                          {"id":"AT_119","count":1,"premiumCount":0}
                                                                         ]
                                           },
                                          {"deck_id":"option_c","cards":[
                                                                         {"id":"CS2_028","count":1,"premiumCount":0},
                                                                         {"id":"EX1_295","count":1,"premiumCount":0},
                                                                         {"id":"GIL_801","count":1,"premiumCount":0}
                                                                         ]
                                            }
                                          ]"
              }
     },
   "feature":"decks"
}

`match`

Info Updates

key	Category	Values	Notes	Since GEP Ver.
localPlayer	playersInfo	See notes		123.0
opponent	playersInfo	See notes		123.0
match_type	match_info	The type of the current match.	See notes	134.0
battlegrounds_rating	match_info	The local player's BG rating.	See notes	143.0
adventure_stats	match_info	The stats of the current adventure run.	See notes	143.0

localPlayer note

"name" – name of local player
"standardRank" – rank of the player in Constructed Standard mode (string)
"standardLegendRank" – rank of the player in Constructed Standard mode, once he reached Legend (int)
"wildRank" – rank of the player in Constructed Wild mode (int)
"wildLegendRank"– rank of the player in Constructed Wild mode, once he reached Legend (int)
"cardBackId" – ID of the card back used in the current game (int)
"cardId" – ID of the card representing the hero (string)

{"playersInfo":{"localPlayer":"{"name":"Overwolf","standardRank":"Bronze 10","standardLegendRank":0,"wildRank":0,"wildLegendRank":0,"cardBackId":157,"cardId":"HERO_05"}"}`

opponent note

"name" – name of the opponent
"standardRank" – The rank of the player in Constructed, in Standard mode (string)
"standardLegendRank"– The rank of the player in Constructed, in Standard mode, once he reached Legend (int)
"wildRank" – The rank of the player in Constructed, in Wild mode (int)
"wildLegendRank – The rank of the player in Constructed, in Wild mode, once he reached Legend (int)
"cardBackId" – the ID of the card back used in the current game (int)
"cardId" – the ID of the card representing the hero (string)

{"playersInfo":{"opponent":"{"name":"furhyax","standardRank":"Bronze 10","standardLegendRank":0,"wildRank":0,"wildLegendRank":0,"cardBackId":172,"cardId":"HERO_09a"}"}`

match_type note

Important: There's a new game mode called "Duels". We do NOT support this mode at this time. We will update accordingly soon.

tip

If you would like to know when the user is going to play the battlegrounds mode, you can listen to the match_type info update, and check If the value is GT_BATTLEGROUNDS.

Data Example:

{"info":{"match_info":{"match_type":"GT_CASUAL"}},"feature":"match"}

{"info":{"match_info":{"match_type":"GT_BATTLEGROUNDS"}},"feature":"match"}

battlegrounds_rating note

Data Example:

{"info":{"match_info":{"battlegrounds_rating":"2153"}},"feature":"match_info"}

adventure_stats note

Data Example:

{
   "info":{
      "match_info":{
         "adventure_stats":"{"adventure_trl":{
         "dungeon_crawl_all_classes_total_boss_wins":29,
         "dungeon_crawl_all_classes_total_run_wins":1,
         "dungeon_crawl_hunter_boss_wins":1,
         "dungeon_crawl_hunter_run_wins":0,
         "dungeon_crawl_paladin_boss_wins":0,
         "dungeon_crawl_paladin_run_wins":0,
         "dungeon_crawl_mage_boss_wins":7,
         "dungeon_crawl_mage_run_wins":0,
         "dungeon_crawl_warlock_boss_wins":6,
         "dungeon_crawl_warlock_run_wins":0,
         "dungeon_crawl_warrior_boss_wins":8,
         "dungeon_crawl_warrior_run_wins":1,
         "dungeon_crawl_shaman_boss_wins":6,
         "dungeon_crawl_shaman_run_wins":0,
         "dungeon_crawl_priest_boss_wins":1,
         "dungeon_crawl_priest_run_wins":0,
         "dungeon_crawl_rogue_boss_wins":0,
         "dungeon_crawl_rogue_run_wins":0,
         "dungeon_crawl_druid_boss_wins":0}}"
      }
   },
   "feature":"match_info"
}

Events

Event	Event Data	Fired When	Notes	Since GEP Ver.
match_start	Wild / Standard	match starts	See notes	123.0
match_end	"win"/"lose"/"tie"/Battlegrounds rank	match ends	See notes	123.0
match_outcome	"WON" / "LOST"	match concludes	This event is not reliable on some rare scenarios, please use `"match_end"` event data instead	134.0

match_start note

Data Example:

{"events":[{"name":"match_start","data":"wild"}]}
{"events":[{"name":"match_start","data":"standard"}]}

match_end note

Data Example:

{"events":[{"name":"match_end","data":"win"}]}
{"events":[{"name":"match_end","data":"lose"}]}
{"events":[{"name":"match_end","data":"tie"}]}
{"events":[{"name":"match_end","data":"7"}]}

match_outcome note

Data Example:

{"events":[{"name":"match_outcome","data":"WON"}]}
{"events":[{"name":"match_outcome","data":"LOST"}]}

`match_info`

Info Updates

key	Category	Values	Notes	Since GEP Ver.
pseudo_match_id	match_info	The ID of the current match.	See notes	134.0

pseudo_match_id note

This is an Overwolf-generated code for internal use, not issued by the game or by Blizzard.

Data Example:

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

`arena`

Info Updates

key	Category	Values	Notes	Since GEP Ver.
arena_draft	arena	Three offered cards during arena draft.	See notes	184.0

arena_draft note

Data Example:

{"info":{"arena":{"arena_draft":"{"cards":["TRL_509","SW_067","SW_319"]}"}},"feature":"arena"}

Sample Apps​

Available Features​

Game events status​

gep_internal​

Info Updates​

gep_internal note​

collection​

Info Updates​

collection note​

scene_state​

Info Updates​

scene_state note​

decks​

Info Updates​

deck_id note​

selected_deck note​

adventure deck note​

adventure_loot_options note​

match​

Info Updates​

localPlayer note​

opponent note​

match_type note​

battlegrounds_rating note​

adventure_stats note​

Events​

match_start note​

match_end note​

match_outcome note​

match_info​

Info Updates​

pseudo_match_id note​

arena​

Info Updates​

arena_draft note​

Sample Apps

Available Features

Game events status

`gep_internal`

Info Updates

gep_internal note

`collection`

Info Updates

collection note

`scene_state`

Info Updates

scene_state note

`decks`

Info Updates

deck_id note

selected_deck note

adventure deck note

adventure_loot_options note

`match`

Info Updates

localPlayer note

opponent note

match_type note

battlegrounds_rating note

adventure_stats note

Events

match_start note

match_end note

match_outcome note

`match_info`

Info Updates

pseudo_match_id note

`arena`

Info Updates

arena_draft note