> 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/kr/api-6/player-status.md).

# 플레이어 상태

\[ 기본 URL: `api.ggwp.com`]

`POST` /users/v1/update-status

## **설명**

GGWP 외부 시스템(예: 플레이어 음소거)을 사용하여 플레이어에 대해 조치를 취할 때 해당 정보를 우리에게 공유하여 시스템상의 상태를 업데이트할 수 있습니다. 아래 가이드는 RESTful Player Status API를 사용하여 이를 수행하는 방법에 대한 지침을 제공합니다. 

게임의 행동 강령에 따라 플레이어의 상태는 다음 사이에서 전환될 수 있습니다 `active`  및  `muted`. 게임의 운영자가 플레이어의 상태를 변경하게 하는 다양한 이벤트가 있을 수 있습니다.

이전에 상태 정보가 전송되지 않은 플레이어는 다음으로 간주됩니다 `알 수 없음`.

## **매개변수**

`본문`: 다음 필드를 포함하는 사전(Dictionary):

* **user\_id**: 상태가 전송되는 플레이어의 ID.
* **status**: 플레이어의 현재 상태. 지원되는 값: `active`, `muted`
  * `active` → 해당 채널에 참여하는 것이 허용된 플레이어입니다.
  * `muted` → 해당 채널에 참여하는 것이 허용되지 않은 플레이어입니다.
* **channel**: 상태 변경이 적용될 채널. 채널에 대한 지원되는 값: `채팅`, `음성`, `discord` 및 `게임`.
* (선택 사항) **expiry\_at:** 형식의 타임스탬프 *YYYY-MM-DD HH:MM:SS* 상태가 만료되어 다시 다음으로 되돌아가야 하는 시점을 나타냅니다 `active`. 상태가 다음으로 설정되는 경우 `active` 이 필드는 데이터를 처리하는 동안 아무 곳에서도 고려되지 않습니다.
* (선택 사항) **updated\_by:** 상태 업데이트를 수행한 시스템 사용자의 이름 또는 이메일.
* (선택 사항) **username:** 상태가 전송되는 사용자의 이름.
  * 이 `username` 필드는 길이가 1에서 128자 사이인 문자열 값을 허용합니다.
  * 만약 `username` 필드가 제공되면 새 사용자의 사용자명을 지정합니다; 사용자가 이미 존재하는 경우 해당 값이 기존 사용자명을 대체합니다.
* 샘플 호출

  ```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>"
  }'
  ```

## **출력**

* 200 - 성공적인 작업

  ```json
  {
      "success": true
  }
  ```
* 400
  * 오류 응답.&#x20;
    * `expiry_at`
      * expiry\_at 필드의 형식이 잘못되었습니다. UTC에서 YYYY-MM-DD HH:MM:SS 형식을 사용하세요.
      * expiry\_at는 미래 날짜여야 합니다.
    * `status`&#x20;
      * status에 대한 유효하지 않은 선택입니다.
    * `channel`&#x20;
      * channel에 대한 유효하지 않은 선택입니다.
    * `username`&#x20;
      * username의 길이가 유효하지 않습니다.
  * 예시
    * ```json
      {
          "error": "channel에 대한 유효하지 않은 선택입니다."
      }
      ```
* 403
  * 잘못되었거나 누락된 API 키
  * 예시
    * ```json
      {
          "error": "유효하지 않거나 누락된 API 키"
      }
      ```
* 500
  * 오류 응답.&#x20;
    * 디스코드 채널에서 사용자 상태 업데이트에 실패했습니다. 유효한 디스코드 사용자를 제공하세요.
    * 사용자 상태를 업데이트하지 못했습니다
  * 예시
    * ```json
      {
          "error": "사용자 상태를 업데이트하지 못했습니다"
      }
      ```
  *