알림톡 템플릿 만들기

알림톡은 자유롭게 본문을 작성해 보내는 메시지가 아닙니다. 먼저 카카오의 검수를 받은 템플릿을 만들고, 발송할 때 #{변수}의 값만 바꿉니다. 이 가이드에서는 배송 시작 안내 템플릿 하나를 처음부터 만들어 API와 SDK에서 사용하는 과정까지 이어서 설명합니다.

완성할 템플릿

템플릿 이름은 콘솔에서 찾기 위한 이름이라 수신자에게 보이지 않습니다. 본문에 #{변수명}을 쓰면 발송 요청의 변수 값으로 치환됩니다.

1. 콘솔에서 템플릿 만들기

알림톡 템플릿에서 새 템플릿을 선택합니다.

1. 템플릿을 사용할 카카오 채널을 선택합니다.
2. 템플릿 이름에 배송 시작 안내 · 문서 예제를 입력합니다.
3. 카테고리에서 배송 > 배송상태를 선택합니다.
4. 강조 표기는 없음을 선택합니다.
5. 본문에 아래 내용을 입력합니다.

#{고객명}님, 주문하신 #{상품명}의 배송이 시작되었습니다.
운송장 번호: #{운송장번호}

오른쪽 미리보기에서 줄바꿈과 변수 위치를 확인한 뒤 저장을 선택합니다. 저장 직후 상태는 작성됨이며 아직 발송할 수 없습니다.

2. 카카오 검수 요청하기

저장된 템플릿의 상세 화면에서 본문, 변수, 카테고리를 다시 확인하고 검수 요청을 선택합니다. 검수 요청이 접수되면 상태가 검수중으로 바뀌며 내용을 수정할 수 없습니다.

검수를 통과하면 상태가 승인됨으로 바뀝니다. API에서는 sendable: true인지 확인하는 것이 가장 정확합니다. 승인 상태여도 휴면 템플릿은 발송할 수 있기 때문입니다.

3. 채널 ID와 템플릿 확인하기

템플릿 생성과 검수 요청은 콘솔에서 진행합니다. 발송 코드에서는 연결된 채널과 승인된 템플릿의 ClawOps 리소스 ID를 조회해 사용합니다.

먼저 연결된 채널을 조회합니다.

$
curl "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/kakao/channels?status=connected" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

응답의 data[].id가 ClawOps 채널 리소스 ID입니다. 카카오 검색용 ID인 searchId와 혼동하지 마세요.

운영 응답에서 이 가이드에 사용할 Equation 채널 행을 발췌하면 다음과 같습니다.

1
{
2
  "data": [
3
    {
4
      "id": "cmth9t8kb004201s61a2kvbzl",
5
      "searchId": "equation",
6
      "name": "Equation",
7
      "categoryCode": "00700090001",
8
      "status": "connected",
9
      "managerPhoneMasked": "010-****-4897",
10
      "connectedAt": "2026-08-31T13:25:03.515Z",
11
      "syncedAt": "2026-08-31T13:25:03.514Z",
12
      "createdAt": "2026-08-31T13:25:03.515Z",
13
      "updatedAt": "2026-08-31T13:25:04.294Z"
14
    }
15
  ],
16
  "meta": { "page": 0, "pageSize": 20, "total": 2 }
17
}

채널 리소스 ID로 템플릿을 조회합니다.

$
curl "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/kakao/templates?channelId=cmth9t8kb004201s61a2kvbzl&pageSize=100" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

운영 응답에서 방금 만든 템플릿 행을 발췌하면 다음과 같습니다.

1
{
2
  "data": [
3
    {
4
      "id": "cmtjnmpvo000j01s6glbpe4h4",
5
      "channelId": "cmth9t8kb004201s61a2kvbzl",
6
      "name": "배송 시작 안내 · 문서 예제",
7
      "content": "#{고객명}님, 주문하신 #{상품명}의 배송이 시작되었습니다.\n운송장 번호: #{운송장번호}",
8
      "status": "PENDING",
9
      "dormant": false,
10
      "sendable": false,
11
      "assignType": "CHANNEL",
12
      "messageType": "BA",
13
      "emphasizeType": "NONE",
14
      "variables": ["#{고객명}", "#{상품명}", "#{운송장번호}"],
15
      "createdAt": "2026-09-02T05:27:26.340Z",
16
      "updatedAt": "2026-09-02T05:27:26.340Z"
17
    }
18
  ],
19
  "meta": { "page": 0, "pageSize": 100, "total": 6 }
20
}

발송에는 채널 응답의 id, 템플릿 응답의 id, 그리고 variables의 모든 항목이 필요합니다.

4. 검수 승인 후 알림톡 한 건 보내기

현재 실측 템플릿은 PENDING, sendable: false이므로 아직 발송할 수 없습니다. 카카오 검수 후 조회 응답이 sendable: true로 바뀐 것을 확인한 다음 아래 코드를 실행합니다.

$
curl -X POST "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/messages" \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "To": "01012345678",
>
    "From": "07012341234",
>
    "Kakao": {
>
      "ChannelId": "cmth9t8kb004201s61a2kvbzl",
>
      "TemplateId": "cmtjnmpvo000j01s6glbpe4h4",
>
      "Variables": {
>
        "고객명": "홍길동",
>
        "상품명": "무선 키보드",
>
        "운송장번호": "1234-5678-9012"
>
      }
>
    },
>
    "Fallback": {
>
      "Body": "홍길동님의 무선 키보드 배송이 시작되었습니다. 운송장 번호: 1234-5678-9012"
>
    }
>
  }'

세 탭은 아래처럼 이름만 각 언어 관례에 맞게 바뀌며 같은 요청 필드를 전송합니다.

Fallback은 알림톡 전달에 실패했을 때 별도의 문자 한 건을 보냅니다. 문자 대체 발송을 원하지 않으면 cURL에서는 "Fallback": { "Disabled": true }, SDK에서는 fallback: { disabled: true } 형태로 지정하세요.

자주 막히는 지점

최종 발송 결과는 요청 응답의 queued만으로 판단하지 말고 message.sent 또는 message.failed 웹훅으로 확인하세요. 더 자세한 발송 규칙은 알림톡 보내기를 참고하세요.