카카오 알림톡 보내기

카카오 알림톡은 자유롭게 본문을 작성해 보내는 메시지가 아닙니다. 카카오가 승인한 템플릿을 선택하고, 발송할 때 템플릿 변수의 값만 채웁니다.

이 가이드의 cURL, TypeScript SDK, Python SDK 예제는 동일한 승인 템플릿으로 각각 한 건씩 실제 발송해 검증했습니다. 세 요청 모두 201 Created로 접수됐고 최종 상태는 sent였습니다.

준비할 값

발신번호는 현재 계정이 보유한 번호여야 합니다. API Key와 Account ID는 환경변수로 설정합니다.

export CLAWOPS_API_KEY="YOUR_API_KEY"
export CLAWOPS_ACCOUNT_ID="YOUR_ACCOUNT_ID"
export CLAWOPS_FROM="07012341234"
export CLAWOPS_TO="01012345678"
export CLAWOPS_KAKAO_CHANNEL_ID="YOUR_CHANNEL_ID"
export CLAWOPS_KAKAO_TEMPLATE_ID="YOUR_TEMPLATE_ID"

SDK를 사용한다면 실행할 언어의 패키지를 설치합니다.

npm install @teamlearners/clawops

1. 발송 가능한 채널 조회하기

연결 상태가 정상인 채널을 조회합니다. cURL과 두 SDK는 같은 API를 호출합니다.

curl "https://api.claw-ops.com/v1/accounts/${CLAWOPS_ACCOUNT_ID}/kakao/channels?status=connected" \
  -H "Authorization: Bearer ${CLAWOPS_API_KEY}"

응답의 data[].id가 발송 요청에 넣을 ClawOps 채널 ID입니다. 카카오 검색용 ID인 searchId를 넣으면 안 됩니다.

{
  "data": [
    {
      "id": "YOUR_CHANNEL_ID",
      "searchId": "your-channel-search-id",
      "name": "내 카카오 채널",
      "status": "connected"
    }
  ],
  "meta": { "page": 0, "pageSize": 20, "total": 1 }
}

2. 승인된 템플릿과 변수 확인하기

앞에서 얻은 채널 ID로 템플릿을 조회합니다. 반드시 sendable: true인 템플릿을 사용하고, variables에 나온 변수를 모두 채워야 합니다.

curl "https://api.claw-ops.com/v1/accounts/${CLAWOPS_ACCOUNT_ID}/kakao/templates?channelId=${CLAWOPS_KAKAO_CHANNEL_ID}&pageSize=100" \
  -H "Authorization: Bearer ${CLAWOPS_API_KEY}"

실측에 사용한 템플릿은 다음과 같습니다.

{
  "id": "YOUR_TEMPLATE_ID",
  "channelId": "YOUR_CHANNEL_ID",
  "name": "인증번호",
  "content": "아래 인증번호를 확인하시고\n서비스 화면에 입력해주세요.\n\n인증번호: #{인증번호}",
  "status": "APPROVED",
  "sendable": true,
  "variables": ["#{인증번호}"]
}

조회 응답은 변수를 #{인증번호} 형태로 표시합니다. 발송 요청의 변수 키에는 인증번호와 #{인증번호}를 모두 사용할 수 있으며, 아래에서는 읽기 쉬운 인증번호를 사용합니다.

조회한 채널과 템플릿의 id를 앞에서 선언한 CLAWOPS_KAKAO_CHANNEL_ID, CLAWOPS_KAKAO_TEMPLATE_ID에 넣으세요. 다른 템플릿을 사용한다면 아래 variables도 그 템플릿의 변수명에 맞게 바꿉니다.

3. 알림톡 한 건 보내기

채널 ID, 템플릿 ID, 템플릿이 요구하는 변수를 전달합니다. 알림톡 본문은 승인된 템플릿이 정하므로 일반 문자 필드인 Body/body를 넣지 않습니다.

curl -X POST "https://api.claw-ops.com/v1/accounts/${CLAWOPS_ACCOUNT_ID}/messages" \
  -H "Authorization: Bearer ${CLAWOPS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "{
    \"To\": \"${CLAWOPS_TO}\",
    \"From\": \"${CLAWOPS_FROM}\",
    \"Kakao\": {
      \"ChannelId\": \"${CLAWOPS_KAKAO_CHANNEL_ID}\",
      \"TemplateId\": \"${CLAWOPS_KAKAO_TEMPLATE_ID}\",
      \"Variables\": { \"인증번호\": \"490001\" }
    },
    \"Fallback\": { \"Disabled\": true }
  }"

세 예제를 공개 배포본인 TypeScript SDK 0.36.0, Python SDK 0.47.0과 cURL로 실행한 결과입니다.

아래 응답은 실측 결과에서 계정 종속 값만 예제 값으로 바꾼 것입니다.

{
  "messageId": "MG0123456789abcdef0123456789abcdef",
  "status": "queued",
  "type": "ata",
  "to": "01012345678",
  "from": "07012341234",
  "body": "아래 인증번호를 확인하시고\n서비스 화면에 입력해주세요.\n\n인증번호: 490001",
  "direction": "outbound",
  "dateCreated": "2026-09-02T06:12:53.867Z",
  "dateUpdated": null
}

type: "ata"가 카카오 알림톡을 뜻합니다. 응답의 body에는 템플릿 변수를 치환한 결과가 들어갑니다. queued는 ClawOps가 요청을 접수했다는 뜻이며 수신자에게 전달됐다는 뜻은 아닙니다.

4. 최종 전달 결과 확인하기

발송 응답의 messageId로 단건 조회합니다. sent가 최종 전달 성공이며, failed라면 응답과 콘솔 메시지 기록에서 실패 사유를 확인합니다.

MESSAGE_ID="YOUR_MESSAGE_ID"
curl "https://api.claw-ops.com/v1/accounts/${CLAWOPS_ACCOUNT_ID}/messages/${MESSAGE_ID}" \
  -H "Authorization: Bearer ${CLAWOPS_API_KEY}"

아래 응답도 실측 결과에서 계정 종속 값만 예제 값으로 바꾼 것입니다.

{
  "messageId": "MG0123456789abcdef0123456789abcdef",
  "status": "sent",
  "type": "ata",
  "to": "01012345678",
  "from": "07012341234",
  "body": "아래 인증번호를 확인하시고\n서비스 화면에 입력해주세요.\n\n인증번호: 490001",
  "dateCreated": "2026-09-02T06:12:53.452Z",
  "dateUpdated": "2026-09-02T06:13:04.731Z"
}

콘솔 메시지 기록에서도 형식이 알림톡, 상태가 발송 완료인지 확인할 수 있습니다. 운영 환경에서는 message.sent와 message.failed 웹훅을 등록해 비동기로 최종 결과를 처리하세요.

REST와 SDK 필드 대응

세 예제는 이름만 각 언어 관례에 맞게 바뀌며 같은 요청 필드를 전송합니다.

Type/type은 생략해도 Kakao/kakao가 있으면 알림톡으로 처리됩니다. 명시한다면 값은 ata입니다.

대체 문자 설정

알림톡 전달 실패 시 SMS/LMS로 대신 보낼 수 있습니다. 대체 문자는 알림톡과 별도의 메시지 한 건으로 기록되며 문자 요금이 별도로 청구됩니다.

자주 막히는 지점

문자 메시지를 보내려면 문자 메시지 가이드를 확인하세요.