# 알림톡 전송

## 1. SendATS - 알림톡 전송

| HTTP Method | 테스트(Sandbox)                             | 운영(Production)                      |
| ----------- | ---------------------------------------- | ----------------------------------- |
| POST        | <https://popbill-test.linkhub.co.kr/ATS> | <https://popbill.linkhub.co.kr/ATS> |

- 승인된 템플릿 내용을 작성하여 다수건의 알림톡 전송을 팝빌에 접수하며, 수신자별 개별 내용 또는 동일 내용을 전송합니다. (최대 1,000건)
- 전송실패시 사전에 지정한 변수 ‘altSendType’ 값으로 대체문자를 전송할 수 있고, 이 경우 문자(SMS/LMS) 요금이 과금됩니다.
- 승인된 템플릿과 일치하지 않는 내용(알림톡 내용, 버튼 목록)을 입력하는 경우 ‘전송실패’ 처리됩니다.
- 수신자 전체에 동일한 내용을 전송하는 동보 전송, 수신자별로 개별 내용을 전송하는 대량 전송을 지원합니다.

### Request

**요청 헤더**

- Authorization `required: Y` `description: 인증 토큰`
  - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/kakaotalk/getting-started/authorization)
- Content-Type `required: Y` `description: 요청 본문 형식`
  - `application/json`
- Accept-Language `required: N` `description: 응답 언어 설정`
  - `ko-KR`: 기본값
  - `en-US`
- Accept-Encoding `required: N` `description: 응답 압축 방식`
  - `gzip`
- X-PB-UserID `required: N` `description: 팝빌회원 아이디`

**요청 본문**

- templateCode `type: string` `length: 12` `required: Y` `description: 승인된 알림톡 템플릿 코드`
- emphasizeTitle `type: string` `length: 50` `required: N` `description: 강조표기 타이틀`
  - 템플릿 예시 : 주문하신 #{상품}이 도착했습니다.
  - 작성 예시 : 주문하신 노트북이 도착했습니다.
  - 동보 전송인 경우 입력
- content `type: string` `length: 1,300` `required: 조건부` `description: 알림톡 내용`
  - 최대 : 1,300자
  - 템플릿 예시 : 주문하신 #{상품}이 도착했습니다.
  - 작성 예시 : 주문하신 노트북이 도착했습니다.
  - 동보 전송인 경우 필수
- snd `type: string` `length: 20` `required: 조건부` `description: 발신번호`
  - 대체문자 전송인 경우 필수
  - 팝빌에 등록되지 않은 발신번호를 입력하는 경우 오류 반환
- altSubject `type: string` `length: 64` `required: N` `description: 대체문자 제목`
  - 대체문자 내용이 90byte 초과한 경우에만 적용
  - 단위 : byte
  - 동보 전송인 경우 입력
- altContent `type: string` `length: 2,000` `required: N` `description: 대체문자 내용`
  - 메시지 길이에 따라 단문(90byte 이하) 또는 장문(90byte 초과)으로 전송
  - 단위 : byte
  - 동보 전송인 경우 입력
- altSendType `type: string` `length: 1` `required: N` `description: 대체문자 유형`
  - `C`: 알림톡 내용 전송
  - `A`: 대체문자 내용 전송
  - 기본값 : 미전송
- sndDT `type: string` `length: 14` `required: N` `description: 전송 예약일시`
  - 형식 : yyyyMMddHHmmss
  - 기본값 : 즉시전송
- requestNum `type: string` `length: 36` `required: N` `description: 요청번호`
  - 파트너가 접수 단위를 식별하기 위해 할당하는 관리번호
  - 영문 대소문자, 숫자, 특수문자('-','\_')만 이용 가능
- btns `type: array` `length: -` `required: N` `description: 버튼 목록`
  - 버튼링크를 변경해야할 경우 사용
  - 최대 : 5개
  - 기본값 : 승인된 템플릿의 버튼 목록
  - 동보 전송인 경우 입력
  - n `type: string` `length: 14` `required: Y` `description: 버튼명`
  - t `type: string` `length: 2` `required: Y` `description: 버튼유형`
    - `WL`: 웹링크
    - `AL`: 앱링크
    - `TN`: 전화걸기
    - `DS`: 배송조회
    - `MD`: 메시지전달
    - `BK`: 봇키워드
    - `AC`: 채널추가
  - u1 `type: string` `length: 1,000` `required: 조건부` `description: 버튼링크`
    - {t} = "AL" 경우 iOS 앱링크 적용
    - {t} = "WL" 경우 Mobile 웹링크 적용
    - {t} = "WL" or "AL" 경우 필수
  - u2 `type: string` `length: 1,000` `required: 조건부` `description: 버튼링크`
    - {t} = "AL" 경우 Android 앱링크 적용
    - {t} = "WL" 경우 PC 웹링크 적용
    - {t} = "WL" or "AL" 경우 필수
  - tg `type: string` `length: 3` `required: N` `description: 아웃 링크`
    - `out`: 디바이스 기본 브라우저
    - 기본값 : 카카오톡 인앱 브라우저 사용
  - telNum `type: string` `length: 14` `required: 조건부` `description: 전화걸기 번호`
    - 숫자, 하이픈(-)만 입력 가능
    - {t} = "TN" 경우 필수
- msgs `type: array` `length: -` `required: Y` `description: 수신자 정보`
  - rcv `type: string` `length: 20` `required: Y` `description: 수신번호`
  - rcvnm `type: string` `length: 70` `required: N` `description: 수신자명`
  - emphasizeTitle `type: string` `length: 50` `required: N` `description: 강조표기 타이틀`
    - 템플릿 예시 : 주문하신 #{상품}이 도착했습니다.
    - 작성 예시 : 주문하신 노트북이 도착했습니다.
    - 대량 전송인 경우 입력
  - msg `type: string` `length: 1,300` `required: 조건부` `description: 알림톡 내용`
    - 최대 : 1,300자
    - 템플릿 예시 : 주문하신 #{상품}이 도착했습니다.
    - 작성 예시 : 주문하신 노트북이 도착했습니다.
    - 대량 전송인 경우 필수
  - altsjt `type: string` `length: 64` `required: N` `description: 대체문자 제목`
    - 대체문자 내용이 90byte 초과한 경우에만 적용
    - 단위 : byte
    - 대량 전송인 경우 입력
  - altmsg `type: string` `length: 2,000` `required: N` `description: 대체문자 내용`
    - 메시지 길이에 따라 단문(90byte 이하) 또는 장문(90byte 초과)으로 전송
    - 대량 전송인 경우 입력
  - interOPRefKey `type: string` `length: 20` `required: N` `description: 파트너 지정키`
    - 카카오톡 대량/동보전송시 파트너가 개별건마다 입력할 수 있는 값
  - btns `type: array` `length: -` `required: N` `description: 버튼 목록`
    - 버튼링크를 변경해야할 경우 사용
    - 최대 : 5개
    - 기본값 : 승인된 템플릿의 버튼 목록
    - 대량 전송인 경우 입력
    - n `type: string` `length: 14` `required: Y` `description: 버튼명`
    - t `type: string` `length: 2` `required: Y` `description: 버튼유형`
      - `WL`: 웹링크
      - `AL`: 앱링크
      - `TN`: 전화걸기
      - `DS`: 배송조회
      - `MD`: 메시지전달
      - `BK`: 봇키워드
      - `AC`: 채널추가
    - u1 `type: string` `length: 1,000` `required: 조건부` `description: 버튼링크`
      - {t} = "AL" 경우 iOS 앱링크 적용
      - {t} = "WL" 경우 Mobile 웹링크 적용
      - {t} = "WL" or "AL" 경우 필수
    - u2 `type: string` `length: 1,000` `required: 조건부` `description: 버튼링크`
      - {t} = "AL" 경우 Android 앱링크 적용
      - {t} = "WL" 경우 PC 웹링크 적용
      - {t} = "WL" or "AL" 경우 필수
    - tg `type: string` `length: 3` `required: N` `description: 아웃 링크`
      - `out`: 디바이스 기본 브라우저
      - 기본값 : 카카오톡 인앱 브라우저 사용
    - telNum `type: string` `length: 14` `required: 조건부` `description: 전화걸기 번호`
      - 숫자, 하이픈(-)만 입력 가능
      - {t} = "TN" 경우 필수

**요청 예시 (단건)**

```bash
curl --request POST \
  --url 'https://{domain}/ATS' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "templateCode": "025080000032",
    "content": "알림톡 내용",
    "msgs": [
        {
            "rcv": "01012345678",
            "rcvnm": "수신자명"
        }
    ],
    "btns": [
        {
            "n": "버튼명",
            "t": "WL",
            "u1": "https://www.popbill.com",
            "u2": "https://www.popbill.com"
        }
    ]
  }'
```

**요청 예시 (대량)**

```bash
curl --request POST \
  --url 'https://{domain}/ATS' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "templateCode": "025050001056",
    "msgs": [
        {
            "rcv": "01012345678",
            "msg": "알림톡 내용",
            "rcvnm": "수신자명",
            "btns": [
                {
                    "n": "버튼명",
                    "t": "WL",
                    "u1": "https://www.popbill.com",
                    "u2": "https://www.popbill.com"
                }
            ]
        }
    ]
}'
```

**요청 예시 (동보)**

```bash
curl --request POST \
  --url 'https://{domain}/ATS' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "templateCode": "025080000032",
    "content": "알림톡 내용",
    "msgs": [
        {
            "rcv": "01012345678",
            "rcvnm": "수신자명"
        }
    ],
    "btns": [
        {
            "n": "버튼명",
            "t": "WL",
            "u1": "https://www.popbill.com",
            "u2": "https://www.popbill.com"
        }
    ]
  }'
```

### Response

**응답 본문**

- receiptNum `type: string` `length: 18` `description: 접수번호`

**응답 예시**

```json
{
    "receiptNum": "025102015544100001"
}
```

## 2. CancelReserve - 예약전송 취소 (접수번호)

| HTTP Method | 테스트(Sandbox)                                                       | 운영(Production)                                                |
| ----------- | ------------------------------------------------------------------ | ------------------------------------------------------------- |
| GET         | <https://popbill-test.linkhub.co.kr/KakaoTalk/{receiptNum}/Cancel> | <https://popbill.linkhub.co.kr/KakaoTalk/{receiptNum}/Cancel> |

- 팝빌에서 반환받은 접수번호로 예약된 카카오톡을 전송 취소합니다. (예약시간 10분 전까지 가능)

### Request

**요청 헤더**

- Authorization `required: Y` `description: 인증 토큰`
  - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/kakaotalk/getting-started/authorization)
- Accept-Language `required: N` `description: 응답 언어 설정`
  - `ko-KR`: 기본값
  - `en-US`
- Accept-Encoding `required: N` `description: 응답 압축 방식`
  - `gzip`
- X-PB-UserID `required: N` `description: 팝빌회원 아이디`

**Query 파라미터**

- receiptNum `type: string` `length: 18` `required: Y` `description: 팝빌에서 할당한 접수번호`
  - 카카오톡 예약전송 요청의 반환값

**요청 예시**

```bash
curl --request GET \
  --url 'https://{domain}/KakaoTalk/{receiptNum}/Cancel' \
  --header 'Authorization: Bearer {token}'
```

### Response

**응답 본문**

- code `type: number` `length: -` `description: API 처리에 대한 응답코드`
  - `1`: 성공
- message `type: string` `length: -` `description: API 처리에 대한 응답메시지`

**응답 예시**

```json
{
    "code": 1,
    "message": "취소 완료"
}
```

## 3. CancelReservebyRCV - 예약전송 부분 취소 (접수번호)

| HTTP Method | 테스트(Sandbox)                                                       | 운영(Production)                                                |
| ----------- | ------------------------------------------------------------------ | ------------------------------------------------------------- |
| POST        | <https://popbill-test.linkhub.co.kr/KakaoTalk/{receiptNum}/Cancel> | <https://popbill.linkhub.co.kr/KakaoTalk/{receiptNum}/Cancel> |

- 팝빌에서 반환받은 접수번호로 접수 건을 식별하여 수신번호에 예약된 카카오톡을 전송 취소합니다. (예약시간 10분 전까지 가능)

### Request

**요청 헤더**

- Authorization `required: Y` `description: 인증 토큰`
  - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/kakaotalk/getting-started/authorization)
- Content-Type `required: Y` `description: 요청 본문 형식`
  - `application/json`
- Accept-Language `required: N` `description: 응답 언어 설정`
  - `ko-KR`: 기본값
  - `en-US`
- Accept-Encoding `required: N` `description: 응답 압축 방식`
  - `gzip`
- X-PB-UserID `required: N` `description: 팝빌회원 아이디`

**Query 파라미터**

- receiptNum `type: string` `length: 18` `required: Y` `description: 팝빌에서 할당한 접수번호`
  - 카카오톡 예약전송 요청의 반환값

**요청 본문**

- receiveNum `type: string` `length: 20` `required: Y` `description: 예약전송 수신번호`

**요청 예시**

```bash
curl --request POST \
  --url 'https://{domain}/KakaoTalk/{receiptNum}/Cancel' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "receiveNum": "01012345678"
  }'
```

### Response

**응답 본문**

- code `type: number` `length: -` `description: API 처리에 대한 응답코드`
  - `1`: 성공
- message `type: string` `length: -` `description: API 처리에 대한 응답메시지`

**응답 예시**

```json
{
    "code": 1,
    "message": "취소 완료"
}
```

## 4. CancelReserveRN - 예약전송 전체 취소 (요청번호)

| HTTP Method | 테스트(Sandbox)                                                       | 운영(Production)                                                |
| ----------- | ------------------------------------------------------------------ | ------------------------------------------------------------- |
| GET         | <https://popbill-test.linkhub.co.kr/KakaoTalk/Cancel/{requestNum}> | <https://popbill.linkhub.co.kr/KakaoTalk/Cancel/{requestNum}> |

- 파트너가 할당한 요청번호로 예약된 카카오톡을 전송 취소합니다. (예약시간 10분 전까지 가능)

### Request

**요청 헤더**

- Authorization `required: Y` `description: 인증 토큰`
  - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/kakaotalk/getting-started/authorization)
- Accept-Language `required: N` `description: 응답 언어 설정`
  - `ko-KR`: 기본값
  - `en-US`
- Accept-Encoding `required: N` `description: 응답 압축 방식`
  - `gzip`
- X-PB-UserID `required: N` `description: 팝빌회원 아이디`

**Query 파라미터**

- requestNum `type: string` `length: 36` `required: Y` `description: 파트너가 할당한 요청번호`

**요청 예시**

```bash
curl --request GET \
  --url 'https://{domain}/KakaoTalk/Cancel/{requestNum}' \
  --header 'Authorization: Bearer {token}'
```

### Response

**응답 본문**

- code `type: number` `length: -` `description: API 처리에 대한 응답코드`
  - `1`: 성공
- message `type: string` `length: -` `description: API 처리에 대한 응답메시지`

**응답 예시**

```json
{
    "code": 1,
    "message": "취소 완료"
}
```

## 5. CancelReserveRNbyRCV - 예약전송 부분 취소 (요청번호)

| HTTP Method | 테스트(Sandbox)                                                       | 운영(Production)                                                |
| ----------- | ------------------------------------------------------------------ | ------------------------------------------------------------- |
| POST        | <https://popbill-test.linkhub.co.kr/KakaoTalk/Cancel/{requestNum}> | <https://popbill.linkhub.co.kr/KakaoTalk/Cancel/{requestNum}> |

- 파트너가 할당한 요청번호로 접수 건을 식별하여 수신번호에 예약된 카카오톡을 전송 취소합니다. (예약시간 10분 전까지 가능)

### Request

**요청 헤더**

- Authorization `required: Y` `description: 인증 토큰`
  - [\[참고\] 인증 및 헤더 설정](https://developers.popbill.com/api-reference/kakaotalk/getting-started/authorization)
- Content-Type `required: Y` `description: 요청 본문 형식`
  - `application/json`
- Accept-Language `required: N` `description: 응답 언어 설정`
  - `ko-KR`: 기본값
  - `en-US`
- Accept-Encoding `required: N` `description: 응답 압축 방식`
  - `gzip`
- X-PB-UserID `required: N` `description: 팝빌회원 아이디`

**Query 파라미터**

- requestNum `type: string` `length: 36` `required: Y` `description: 파트너가 할당한 요청번호`

**요청 본문**

- receiveNum `type: string` `length: 20` `required: Y` `description: 예약전송 수신번호`

**요청 예시**

```bash
curl --request POST \
  --url 'https://{domain}/KakaoTalk/Cancel/{requestNum}' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "receiveNum": "01012345678"
  }'
```

### Response

**응답 본문**

- code `type: number` `length: -` `description: API 처리에 대한 응답코드`
  - `1`: 성공
- message `type: string` `length: -` `description: API 처리에 대한 응답메시지`

**응답 예시**

```json
{
    "code": 1,
    "message": "취소 완료"
}
```