# 업데이트

`POST` `https://api.pushwoosh.com/messaging/v2/update`

`message_code`로 식별되는 이전에 생성된 메시지를 새로운 정의로 교체합니다. 교체는 **패치가 아닌 전체 교체**입니다. 즉, 새로운 정의는 전송된 그대로 적용되며 `message_code`는 변경되지 않습니다.

업데이트는 메시지가 아직 **보류 중(pending)** 상태일 때만 가능합니다. 즉, 미래의 전송으로 예약되었지만 아직 처리 또는 전송을 위해 선택되지 않은 상태입니다.

<Aside type="caution" title="중요">

- `request` 필드는 완전한 [`Notify`](/ko/developer/api-reference/messaging-api-v2/notify/) 정의입니다. 생략한 필드는 원본 메시지에서 가져오지 않고 **재설정됩니다**. 변경된 부분만이 아닌, 원하는 전체 메시지를 보내야 합니다.

- 메시지가 이미 처리 중이거나, 전송되었거나, 취소되었거나, 삭제된 경우 API는 `400`을 반환합니다. 이 호출은 멱등성(idempotent)이 없습니다. 업데이트하기 전에 메시지 상태를 확인하세요.
</Aside>

메시지가 아직 업데이트 가능한 상태인지 확인하려면 [메시지 상태 확인](#checking-message-status)을 참조하세요.


## 요청

`Authorization: Token <API_TOKEN>` 헤더에 [서버 API 토큰](/ko/developer/api-reference/api-access-token/#server-api-token)으로 인증합니다.

| 필드 | 유형 | 필수 | 설명 |
|---|---|---|---|
| `message_code` | string | 예 | 업데이트할 메시지의 [메시지 코드](/ko/developer/api-reference/api-identifiers/#message-code). [`Notify`](/ko/developer/api-reference/messaging-api-v2/notify/)가 `result.message_code`에서 반환한 값입니다. |
| `request` | object | 예 | 메시지의 전체 새 정의. [`Notify`](/ko/developer/api-reference/messaging-api-v2/notify/) 요청 본문과 동일한 형태(`segment` 또는 `transactional` 객체)입니다. `Notify`와 똑같이 유효성 검사를 받습니다. |

### 요청 예시

세그먼트 메시지를 다시 예약하고 내용을 변경합니다:

```bash
curl -X POST https://api.pushwoosh.com/messaging/v2/update \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message_code": "XXXX-XXXXXXXX-XXXXXXXX",
    "request": {
      "segment": {
        "application": "XXXXX-XXXXX",
        "platforms": ["IOS", "ANDROID"],
        "code": "active_users",
        "payload": {
          "content": {
            "localized_content": {
              "en": {
                "ios":     { "body": "Updated message" },
                "android": { "body": "Updated message" }
              }
            }
          }
        },
        "schedule": { "at": "2026-05-02T12:00:00Z" },
        "message_type": "MESSAGE_TYPE_MARKETING"
      }
    }
  }'
```

## 응답

성공 시, 업데이트된 메시지의 결과와 함께 HTTP 200을 반환합니다. `message_code`는 변경되지 않습니다.

```json
{
  "result": {
    "message_code": "XXXX-XXXXXXXX-XXXXXXXX",
    "unknown_identifiers": []
  }
}
```

- `message_code` (문자열): 요청에서 전달된 것과 동일한 코드입니다.
- `unknown_identifiers` (문자열 배열): 해당되는 경우, 새 정의에서 찾을 수 없는 식별자입니다 ([`Notify`](/ko/developer/api-reference/messaging-api-v2/notify/) 참조).

## 오류

오류는 표준 gRPC-Gateway 오류 봉투(envelope)를 사용합니다: `{ "code": ..., "message": ..., "details": [...] }`.

| HTTP 상태 | 조건 |
|---|---|
| `400` | `message_code`가 누락되었습니다. |
| `400` | 새 `request` 정의가 누락되었거나 유효하지 않습니다 ([`Notify`](/ko/developer/api-reference/messaging-api-v2/notify/)와 똑같이 유효성 검사를 받습니다). |
| `400` | 메시지가 업데이트 가능한 상태가 아닙니다 (더 이상 `pending` 상태가 아님). |
| `403` | 메시지가 다른 계정에 속해 있습니다. |
| `404` | 주어진 `message_code`에 대한 메시지가 존재하지 않습니다. |
| `500` | 메시지를 로드하거나 업데이트를 적용하는 동안 내부 오류가 발생했습니다. 요청을 다시 시도하세요. |


**예시**

더 이상 존재하지 않는 메시지를 업데이트하면 HTTP `404`가 반환됩니다:

```json
{
  "code": 5,
  "message": "message not found",
  "details": []
}
```

## 메시지 상태 확인

업데이트하기 전에 메시지가 아직 업데이트 가능한 상태인지 확인할 수 있습니다. Control Panel의 메시지 테이블([**캠페인 → 일회성 메시지**](/ko/product/statistics-and-analytics/message-history/))에서 **상태** 열을 읽는 것 외에도, [`messages:list`](/ko/developer/api-reference/statistics-api/message-statistics-api/#messageslist)를 사용하여 프로그래밍 방식으로 상태를 쿼리할 수 있습니다:

- `filters.messages_codes` 배열에 `message_code`를 전달합니다 (필수 `filters.application`과 함께).
- `items[]`에서 일치하는 항목의 `status` 필드를 읽습니다.

<Aside type="note">
`messages:list`는 Statistics API의 일부이며 이 엔드포인트와 다른 인증 헤더를 사용합니다: `Authorization: Api <Server Key>`.
</Aside>

## 관련 항목

<CardGrid>
  <LinkCard title="Notify" href="/developer/api-reference/messaging-api-v2/notify/" />
  <LinkCard title="Cancel" href="/developer/api-reference/messaging-api-v2/cancel/" />
  <LinkCard title="메시지 통계" href="/developer/api-reference/statistics-api/message-statistics-api/#messageslist" />
  <LinkCard title="Messaging API v2 개요" href="/developer/api-reference/messaging-api-v2/" />
  <LinkCard title="v1에서 마이그레이션" href="/developer/api-reference/messaging-api-v2/migration-from-v1/" />
</CardGrid>