> ## Documentation Index
> Fetch the complete documentation index at: https://developer.alltalk.co.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# 알림톡 발송

> 등록한 비즈니스 채널에 승인된 템플릿을 통한 알림톡을 전송합니다.

<Note>
  알림톡은 카카오 승인을 받은 템플릿만 발송할 수 있습니다.
</Note>

## Base URL

```
https://api.alltalk.co.kr
```

## Headers

<ParamField header="apikey" type="string" required>
  제공받은 API key
</ParamField>

## Body (JSON)

<ParamField body="service" type="number" required>
  제공받은 알림톡 서비스 번호
</ParamField>

<ParamField body="template" type="string" required>
  등록된 템플릿 코드 (BizCode)
</ParamField>

<ParamField body="groupId" type="string" required>
  그룹코드
</ParamField>

<ParamField body="message" type="string" required>
  등록된 템플릿 메시지
</ParamField>

<ParamField body="numbers" type="object[]" required>
  수신자 배열. 각 항목은 아래 필드로 구성됩니다.

  * `key` (number): unique key
  * `hp` (string): 수신자 핸드폰 번호
  * `name` (string): 수신자 이름
  * `VAR1`, `VAR2`, ... (string): 템플릿에서 사용한 가변변수에 대입될 값 (N개)
</ParamField>

<ParamField body="title" type="string">
  타이틀 템플릿인 경우 필수. 템플릿 등록에 사용한 title
</ParamField>

<ParamField body="alter" type="boolean" default="false">
  대체문자 발송 여부
</ParamField>

<ParamField body="callbackNo" type="string">
  대체문자 발송 시 발신번호 (`alter=true` 시 필수).
  사전에 등록된 발신번호만 사용 가능합니다.
</ParamField>

## 예제

<RequestExample>
  ```javascript Node.js theme={null}
  const contents = `예약 현황을 알려드립니다.

  [예약 정보]
  - 예약자명 : #{이름}
  - 예약번호 : #{VAR1}
  - 프로그램명 : #{VAR2}
  - 장소 : #{VAR3}
  - 이용일시 : #{VAR4}
  - 이용인원 : #{VAR5}
  - 이용요금 : #{VAR6}
  - 예약상태 : #{VAR7}`;

  const talkData = {
    service: 1234567890,
    message: contents,
    title: '',
    numbers: [
      {
        key: 1,
        hp: '010-1234-5678',
        name: '홍길동',
        VAR1: 'RC0001',
        VAR2: '샘플프로그램',
        VAR3: '프로그램 장소',
        VAR4: '2023-12-30 11:00',
        VAR5: '3인',
        VAR6: '1,000원',
        VAR7: '예약완료',
      },
      {
        key: 2,
        hp: '010-5678-1234',
        name: '이름2',
        VAR1: 'RC0002',
        VAR2: '샘플프로그램',
        VAR3: '프로그램 장소',
        VAR4: '2024-12-31 11:00',
        VAR5: '1인',
        VAR6: '2,000원',
        VAR7: '예약완료',
      },
    ],
    template: '10000',
    groupId: 'YOUR_GROUP_ID',
  };

  await axios.post('https://api.alltalk.co.kr/alimTalk', talkData, {
    headers: { apikey: 'YOUR_API_KEY' },
  }).then(() => {
    alert('전송되었습니다.');
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "version": "1.0.0",
    "status": "success",
    "code": 200,
    "datetime": "2023-12-14 11:43:11",
    "url": "",
    "message": "",
    "value": [
      {
        "uid": 37668015179,
        "date": 1750383559053,
        "status": "OK"
      },
      {
        "uid": 37668015174,
        "date": 1750383559049,
        "status": "KKO_3015"
      }
    ],
    "count": 0,
    "total": 0
  }
  ```
</ResponseExample>

## 응답 필드

| 필드               | 설명                                                                    |
| ---------------- | --------------------------------------------------------------------- |
| `version`        | API 버전                                                                |
| `status`         | `success` / `fail`                                                    |
| `code`           | HTTP 상태 코드                                                            |
| `datetime`       | 응답 시각                                                                 |
| `value[].uid`    | 수신자별 발송 식별자. 발송 결과 상세 조회에 사용                                          |
| `value[].date`   | 발송 시각 (epoch ms)                                                      |
| `value[].status` | 수신자별 결과 코드. `OK` / `KKO_*` / `ERR_*` ([에러코드](/guides/error-codes) 참조) |
| `count`          | 처리된 건수                                                                |
| `total`          | 전체 요청 건수                                                              |

## 참고

* `numbers` 배열의 각 항목은 개별 발송 단위입니다. 한 요청으로 다수에게 발송할 수 있습니다.
* 템플릿의 가변변수(`#{VAR1}`, `#{이름}` 등)와 `numbers[].VARn`, `numbers[].name` 필드가 매핑됩니다.
* 발송 실패(`KKO_*`) 시 `alter: true`로 설정하면 자동으로 SMS 대체 발송이 진행됩니다.