> For the complete documentation index, see [llms.txt](https://docs.ggwp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ggwp.com/api-docs-contextual-information/player-status.md).

# Player Status

\[ Base URL: `api.ggwp.com`]

`POST` /users/v1/update-status

## **Description**

When you take action on a player using a system outside of GGWP (e.g. muting a player), you can share that information with us so that we can update their status in our system. The guide below provides guidance on how to do that using our RESTful Player Status API. 

Based on a game’s code of conduct, the status of a player might shift amongst `active`  and  `muted`. There could be various events which can make a game’s moderators change the status of players.

Players whose status information has not been sent previously are considered `unknown`.

## **Parameters**

`body`: Dictionary containing the following fields:

* **user\_id**: ID of the player whose status is being sent.
* **status**: current status of the player. Supported values: `active`, `muted`
  * `active` → The player is allowed to participate in the corresponding channel.
  * `muted` → The player is not allowed to participate in the corresponding channel.
* **channel**: Channel for which the status change has to be applied. Supported values for channel: `chat`, `voice`, `discord` and `game`.
* (OPTIONAL) **expiry\_at:** Timestamp in the format *YYYY-MM-DD HH:MM:SS* indicating when the status needs to expire and revert to `active`. When the status is being set to `active` then this field is not considered anywhere while processing the data.
* (OPTIONAL) **updated\_by:** Name or email of the system user who made the status update.
* (OPTIONAL) **username:** Name of the user whose status is being sent.
  * The `username` field accepts a string value, with a length ranging from 1 to 128 characters.
  * If the `username` field is provided, it assigns the username for a new user; if the user already exists, the value overrides the existing username.
* Sample Call

  ```bash
  curl --request POST 'https://api.ggwp.com/users/v1/update-status' \
  --header 'x-api-key: api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "user_id": "<id1>",
    "status": "active",
    "expiry_at": "2022-12-30 07:44:37",
    "channel": "chat",
    "username": "<username>"
  }'
  ```

## **Output**

* 200 - successful operation

  ```json
  {
      "success": true
  }
  ```
* 400
  * Error responses.&#x20;
    * `expiry_at`
      * expiry\_at field is in wrong format, use YYYY-MM-DD HH:MM:SS in UTC.
      * expiry\_at should be a future date.
    * `status`&#x20;
      * Not a valid choice for: status.
    * `channel`&#x20;
      * Not a valid choice for: channel.
    * `username`&#x20;
      * Invalid length for: username.
  * Example
    * ```json
      {
          "error": "Not a valid choice for: channel."
      }
      ```
* 403
  * Invalid or missing API key
  * Example
    * ```json
      {
          "error": "Invalid or missing API key"
      }
      ```
* 500
  * Error responses.&#x20;
    * Failed to update user status in the discord channel. Please provide a valid discord user.
    * Couldn't update user's status
  * Example
    * ```json
      {
          "error": "Couldn't update user's status"
      }
      ```
  *