Quests

Quests are a way for Discord to promote games and other content to users. Users can receive rewards for completing quests, such as redeemable codes, in-game items, or collectibles.

Quest Object

A sponsored quest.

Quest Structure

¹ Some quest content areas may be dismissed using the Dismiss Quest Content endpoint.

Partial Quest Structure

Quest Config Object

The quest definition.

Quest Config Structure

The config structure has multiple distinct versions with different field sets. Only actively used versions are kept documented. As of now, only the latest version is available.

Quest Rollout Structure

Quest Application Structure

Quest Assets Structure

An object holding CDN asset names.

Quest Gradient Structure

A 2-point gradient with a primary and secondary color.

Quest Messages Structure

Quest Task Config Structure

¹ For a task to be considered complete, the user must complete either all tasks (when join_operator is and) or at least one task (when join_operator is or).

Quest Task Structure

Quest Task Config Type

Quest Task Event Name

Quest Rewards Config Structure

Quest Reward Structure

¹ If the amount of users who claimed the awards exceeds this count, then all future claimers will be assigned the next reward tier in the list.

Quest Reward Messages Structure

Quest Reward Assignment Method

The method used to assign the reward to a user.

Quest Reward Type

The type of reward that the user will receive.

Quest Reward Expiration Mode

Controls the expiration behavior of COLLECTIBLE rewards.

Quest Video Metadata Structure

Quest Video Messages Structure

Quest Video Assets Structure

Quest Config Version

The version of the quest configuration.

Quest Content Type

Areas where the quest can be shown in the Discord client.

Quest Platform Type

Specifies the platforms that the quest reward can be redeemed on.

Quest Feature

A behavioral variant for a quest.

Example Quest

{
  "id": "8206816794116096000",
  "config": {
    "id": "8206816794116096000",
    "config_version": 2,
    "starts_at": "2025-02-21T18:00:00+00:00",
    "expires_at": "2025-02-28T01:00:00+00:00",
    "features": [3, 9, 12, 14, 15, 16],
    "experiments": {
      "rollout": "2025-02_alien",
      "targeting": null,
      "preview": "2025-02_alien_preview"
    },
    "application": {
      "link": "https://alien.studios/cyberalien",
      "id": "891436233903964161",
      "name": "Cyberalien 2077"
    },
    "assets": {
      "hero": "hero.jpg",
      "hero_video": "hero.mp4",
      "quest_bar_hero": "questbar.jpg",
      "quest_bar_hero_video": "questbar.mp4",
      "game_tile": "gametile.jpg",
      "logotype": "wordmark.png"
    },
    "colors": {
      "primary": "#E944D4",
      "secondary": "#5318A7"
    },
    "messages": {
      "quest_name": "Kill the Aliens",
      "game_title": "Cyberalien 2077",
      "game_publisher": "Alien Studios"
    },
    "task_config": {
      "type": 1,
      "join_operator": "or",
      "tasks": {
        "PLAY_ON_DESKTOP": {
          "event_name": "PLAY_ON_DESKTOP",
          "target": 900,
          "external_ids": []
        },
        "PLAY_ON_XBOX": {
          "event_name": "PLAY_ON_XBOX",
          "target": 900,
          "external_ids": ["267696969"]
        },
        "PLAY_ON_PLAYSTATION": {
          "event_name": "PLAY_ON_PLAYSTATION",
          "target": 900,
          "external_ids": ["CUSA42069_00"]
        }
      }
    },
    "rewards_config": {
      "assignment_method": 1,
      "rewards": [
        {
          "type": 1,
          "sku_id": "1342624440894361624",
          "asset": "CYBERNETIC_HEADGEAR_HELL_YEAHHH.png",
          "asset_video": null,
          "messages": {
            "name": "Cybernetic Headgear",
            "name_with_article": "a Cybernetic Headgear",
            "redemption_instructions_by_platform": {
              "0": "Reward Instructions:\nGo to https://alien.studios/redeem\nEnter your code\nClaim your reward!"
            }
          },
          "approximate_count": null,
          "redemption_link": "https://alien.studios/redeem"
        }
      ],
      "rewards_expire_at": "2025-03-28T00:00:00+00:00",
      "platforms": [0]
    }
  },
  "user_status": null,
  "targeted_content": [],
  "preview": false
}

Claimed Quest Object

A claimed quest.

Claimed Quest Structure

Claimed Quest Config Structure

Claimed Quest Reward Structure

Example Claimed Quest

{
  "id": "8206816794116096000",
  "config": {
    "id": "8206816794116096000",
    "starts_at": "2025-02-21T18:00:00+00:00",
    "expires_at": "2025-02-28T01:00:00+00:00",
    "features": [3, 9, 12, 14, 15, 16],
    "colors": {
      "primary": "#E944D4",
      "secondary": "#5318A7"
    },
    "assets": {
      "hero": "hero.jpg",
      "hero_video": "hero.mp4",
      "quest_bar_hero": "questbar.jpg",
      "quest_bar_hero_video": "questbar.mp4",
      "game_tile": "gametile.jpg",
      "logotype": "wordmark.png"
    },
    "messages": {
      "quest_name": "Kill the Aliens",
      "game_title": "Cyberalien 2077",
      "game_publisher": "Alien Studios"
    },
    "rewards": [
      {
        "sku_id": "1342624440894361624",
        "type": 1,
        "name": "Cybernetic Headgear",
        "name_with_article": "a Cybernetic Headgear",
        "asset": "CYBERNETIC_HEADGEAR_HELL_YEAHHH.png",
        "asset_video": null,
        "orb_quantity": null
      }
    ]
  },
  "user_status": null
}

Quest User Status Object

The user's quest progression.

Quest User Status Structure

¹ These fields are only used for quest config version 1, where the event is always STREAM_ON_DESKTOP.

Quest Task Progress Structure

¹ Heartbeats are only present for events STREAM_ON_DESKTOP, PLAY_ON_DESKTOP, PLAY_ON_DESKTOP_V2, and PLAY_ACTIVITY.

Quest Task Heartbeat Structure

Dismissible Quest Content Flags

Dismissed quest content areas.

¹ This flag dismisses any QUEST_BAR content area, including QUEST_BAR, QUEST_BAR_V2, and QUEST_BAR_MOBILE.

Example Quest User Status

{
  "user_id": "222069018507345921",
  "quest_id": "8206816794116096000",
  "enrolled_at": "2077-01-01T11:59:59+00:00",
  "completed_at": "2077-01-01T11:59:59+00:00",
  "claimed_at": "2077-01-01T11:59:59+00:00",
  "claimed_tier": null,
  "last_stream_heartbeat_at": null,
  "stream_progress_seconds": 0,
  "dismissed_quest_content": 0,
  "progress": {
    "PLAY_ON_DESKTOP": {
      "value": 900,
      "event_name": "PLAY_ON_DESKTOP",
      "updated_at": "2025-03-11T18:19:54.189229+00:00",
      "completed_at": "2025-03-11T18:19:54.189231+00:00",
      "heartbeat": {
        "last_beat_at": "2077-01-01T11:59:59+00:000",
        "expires_at": null
      }
    }
  }
}

Quest Reward Code Object

An object that holds the quest's reward code.

Quest Reward Code Structure

Example Quest Reward Code

{
  "quest_id": "8206816794116096000",
  "code": "111-1111111",
  "platform": 0,
  "user_id": "222069018507345921",
  "claimed_at": "2077-01-01T18:41:29.706194+00:00",
  "tier": null
}

Endpoints

Get Current Quests

Returns information on the current quests for the current user.

Response Body

Get Claimed Quests

Returns information on the claimed quests for the current user.

Response Body

Get Quest Config

Returns a quest config object for the specified quest. Quest must be currently active.

Get Quest Placement

Returns the quest that should be shown to the user in a specific placement.

Query Params

Quest Placement Area

Response Body

Accept Quest

Accepts a quest and returns a quest user status object. Fires a Quests User Status Update Gateway event.

JSON Params

Claim Quest Reward

Claims the quest's rewards, setting the completed_at and claimed_at fields of the quest user status to the current timestamp. Fires a Quests User Status Update Gateway event.

JSON Params

Response Body

Entitlement Expiration Metadata Structure

Example Response

{
  "claimed_at": "2024-04-17T23:30:41.000321+00:00",
  "entitlement_expiration_metadata": {
    "1230299425620885624": {
      "extended": false,
      "extendable": true
    }
  },
  "entitlements": [
    {
      "id": "1230299425620885624",
      "sku_id": "1226939756617793606",
      "application_id": "1242265603276800000",
      "user_id": "222069018507345921",
      "deleted": false,
      "starts_at": null,
      "ends_at": null,
      "type": 10,
      "tenant_metadata": {},
      "gift_code_flags": 0,
      "promotion_id": null
    }
  ],
  "errors": []
}

Get Quest Reward Code

Retrieves the reward code for the specified platform. Returns a quest reward code object on success.

Send Quest Heartbeat

Tells the server to update the value and heartbeat fields of the current task. Used for keeping track of how long the stream has been running for, and for checking if the user has met the task duration requirement. Returns a quest user status object on success. Fires a Quests User Status Update Gateway event.

JSON Params

¹ For heartbeats without an associated stream, a special stream key of call:<quest_id>:1 should be used, where <quest_id> is the ID of the quest.

Send Quest Video Progress

Tells the server to update the value field of the current video task. Used for keeping track of how long the video has been watched for, and for checking if the user has met the task duration requirement. Returns a quest user status object on success. Fires a Quests User Status Update Gateway event.

JSON Params

Start Console Quest

Starts completing a quest on console. Fires a Quests User Status Update Gateway event.

Query Params

Response Body

Quest Error Hint Structure

Example Response

{
  "started": false,
  "quest_user_status": null,
  "error_hints": ["Xbox account DiscordGamer seems to be offline."],
  "error_hints_v2": [
    {
      "type": "no_game_offline",
      "message": "Xbox account DiscordGamer seems to be offline.",
      "connected_account_id": "3076467402341699",
      "connected_account_type": "xbox"
    }
  ]
}

Stop Console Quest

Stops completing a quest on console. Returns a 204 empty response on success. Fires a Quests User Status Update Gateway event.

Complete Quest

Forcefully completes the quest for the current user. Returns a quest user status object. Fires a Quests User Status Update Gateway event.

Reset Quest

Resets the quest's status for the current user. Returns a quest user status object. Fires a Quests User Status Update Gateway event.

Dismiss Quest Content

Dismisses the specified quest content area for the current user. Not all content areas can be dismissed. Returns a quest user status object. Fires a Quests User Status Update Gateway event.

Reset Quest Dismissibility

Resets the dismissibility of the quest's content areas for the current user (sets the dismissed_quest_content field to 0). Returns a quest user status object. Fires a Quests User Status Update Gateway event.