# 액션 버튼

알림에는 최대 세 개의 버튼을 넣을 수 있습니다. 알림을 읽은 뒤 노트북을 열어 처리할 필요 없이, 잠금 화면에서 바로 처리하세요. 실행 기록을 열고, 재시작을 실행하고, 코드를 복사할 수 있습니다.

## 버튼 유형 세 가지

| 유형 | 버튼 동작 | `value` 값 |
|------|----------------------|---------------|
| `view` | URL을 엽니다 | URL, 예: `https://status.example.com` |
| `http` | 백그라운드에서 HTTP 요청을 보냅니다 | JSON 문자열: `{"url":"…","method":"POST","headers":{…},"body":"…"}` |
| `copy` | 텍스트를 클립보드에 복사합니다 | 복사할 텍스트 그대로 |

`http` 유형에서는 `url`만 필수입니다. `method`를 생략하면 `GET`이 기본값으로 쓰입니다. `body`가 있고 콘텐츠 타입을 지정하지 않았다면 `Content-Type: application/json`이 자동으로 추가됩니다.

`http`와 `copy` 버튼은 앱이 종료된 상태에서도 앱을 열지 않고 실행됩니다. `view` 버튼은 앱이나 브라우저를 앞으로 가져옵니다.

## 버튼이 표시되는 위치

버튼은 iOS와 안드로이드 모두에서 시스템 알림에 표시됩니다. 앱이 열려 있든, 백그라운드에 있든, 종료되어 있든 마찬가지입니다. 메시지 안에도 버튼이 남아 있습니다. 이 점이 중요합니다. 배너를 밀어서 지워도, 나중에 메시지를 열면 버튼을 그대로 사용할 수 있습니다.

- **레이블**은 보내신 그대로 두 플랫폼 모두에 표시됩니다. iOS가 제한 시간 안에 커스텀 버튼을 준비하지 못하면, 유형별 기본 레이블인 **열기**, **실행**, **복사**로 대체되며 버튼은 그대로 작동합니다.
- **잠금 화면.** `http`와 `copy` 버튼은 잠금을 해제하지 않아도 잠금 화면에서 실행됩니다. `view` 버튼은 앱이나 브라우저를 열기 때문에 먼저 잠금을 해제해야 합니다. 안드로이드에서는 잠금 화면이 알림 내용을 표시하도록 설정되어 있을 때만 버튼이 잠금 화면에 나타납니다.
- **요청 실패.** `http` 요청이 실패하면(2xx/3xx가 아닌 상태 코드이거나 네트워크 오류인 경우) **재시도** 버튼이 있는 알림이 나타납니다. 서버에 이미 도달했을 수 있는 요청은 자동으로 재시도되지 않습니다.
- **앱 버전.** 시스템 알림 버튼은 Pocket Alert 앱 2.0.1 이상에서 지원됩니다. 이전 버전에서는 메시지 안에서만 버튼이 표시됩니다.

## 승인 워크플로

**승인**과 **거절** 두 개의 `http` 버튼을 넣으면, 알림이 한 번의 탭으로 조작하는 제어판이 됩니다. 사람의 확인을 기다리며 멈춰 있는 작업이라면 무엇에든 이 방식을 쓸 수 있습니다.

- 수동 승인을 기다리며 멈춰 있는 배포 파이프라인
- 돈을 쓰거나 운영 환경을 건드리기 전에 승인이 필요한 LLM 에이전트
- 기준 금액을 넘는 환불
- 문, 게이트, 조명, 차고 문

요청은 휴대폰에서 엔드포인트로 바로 전송됩니다. Pocket Alert가 요청을 중계하지 않으며, 응답 본문도 확인하지 않습니다.

> **Warning: 멱등성은 직접 관리하세요**
>
> 같은 `http` 버튼을 두 번 누르면 요청도 두 번 전송됩니다. 반복 요청을 막지 않습니다. 중복 실행의 비용이 크다면 엔드포인트를 멱등하게 만드세요.

## 웹훅에서 만드는 버튼

웹훅에는 `%path%` 플레이스홀더가 들어간 액션 템플릿을 담을 수 있습니다. 이 플레이스홀더는 수신한 페이로드의 값으로 채워집니다. 예를 들어 Sentry 알림이 도착하면 해당 이슈를 가리키는 **이슈 열기** 버튼이 함께 표시되고, Stripe 이벤트에는 해당 결제 건을 가리키는 **결제 보기** 버튼이 표시됩니다.

치환되는 값은 템플릿을 파싱하기 전에 JSON 이스케이프 처리됩니다. 따옴표가 들어간 페이로드 필드가 URL을 망가뜨리거나 바꿔 쓸 수 없습니다. 버튼이 잘못된 값으로 변환되면, 예를 들어 알림에 런북 URL이 없는데 **런북** 버튼이 만들어지면, 그 버튼만 제외됩니다. 나머지 버튼과 메시지는 정상적으로 전달됩니다. 잘못된 버튼 하나 때문에 알림을 놓치는 일은 없습니다.

웹훅을 만들거나 수정할 때 콘솔에서 템플릿을 설정할 수 있고, [웹훅 API](https://info.pocketalert.app/api/webhooks/create.md#action-buttons-template)를 통해 설정할 수도 있습니다.

## 제한과 검증

- 메시지당 최대 **3**개의 버튼을 지원하며, 보내신 순서대로 표시됩니다.
- `actions` 배열은 JSON 인코딩 후 최대 **2048바이트**입니다. 이 배열은 최대 4 KB인 푸시 알림 안에 함께 전송되므로, 공간을 확보하기 위해 긴 `message`는 줄여서 전송됩니다.
- `view`와 `http`는 유효한 `http(s)` URL이어야 합니다. 그 밖의 값은 API에서 `400`을 반환합니다. 웹훅 템플릿에서는 잘못된 버튼이 제외됩니다.
- 알 수 없는 `type` 값은 `400`을 반환합니다.

> **Warning: 유료 기능**
>
> 무료 플랜에서는 서버에서 메시지의 액션 버튼이 제거됩니다. 메시지 자체는 정상적으로 전달됩니다.

## 관련 문서

- [메시지 생성](https://info.pocketalert.app/api/messages/create.md) — `actions` 배열과 전체 요청 레퍼런스
- [우선순위 수준](https://info.pocketalert.app/features/priority-levels.md) — 알림이 얼마나 강하게 울리는지
- [웹훅 설정](https://info.pocketalert.app/api/webhooks/settings.md) — 수신 웹훅의 액션 템플릿
