본문으로 건너뛰기

알림톡 API, 발송 연동 순서와 실패 시 문자 대체 설정

알림톡 API를 공식 딜러사 API로 붙이는 6단계(채널 준비 · 딜러사 계약 · 템플릿 검수 · 발신번호 등록 · 서버 연동 · 시험 발송), 주문 확인 · 배송 시작 · 예약 확정 템플릿의 변수 설계 예, 중복 발송을 막는 키, 실패 결과별로 문자 대체 발송을 할지 고르는 처리표를 정리했습니다.

알림톡 API, 발송 연동 순서와 실패 시 문자 대체 설정

알림톡 API는 카카오에 직접 붙이지 않고, 카카오와 계약한 공식 딜러사(발송 대행사)의 API로 연동합니다. 템플릿을 먼저 등록해 검수를 통과시키고, 프로그램은 승인된 템플릿 코드에 바뀌는 값(변수)만 채워 보내며, 카카오톡으로 닿지 않은 건은 문자로 대신 나가도록 대체 발송을 설정하는 순서입니다. 이 글은 개발 연동만 다루고, 템플릿 반려 사유와 비용 계산은 카카오 알림톡, 템플릿 반려 7가지와 비용 계산에 있습니다.

알림톡 API는 누구를 통해 연동하나요

카카오비즈니스 가이드는 알림톡을 공식 딜러사를 통해 진행하며, 딜러사마다 서비스 범위와 발송 단가 같은 계약 조건이 다를 수 있다고 안내합니다. 개발자가 받는 것은 딜러사의 API 문서와 인증 값입니다. 한 딜러사(NHN Cloud) 문서를 예로 들면 요청 머리에 비밀 키를 넣고, 본문에 발신 키(카카오톡 채널을 발신 프로필로 등록하면 받는 값) · 템플릿 코드 · 받는 번호 · 변수 값을 담아 보냅니다. 받는 사람은 한 번에 1,000명까지 담을 수 있고, 발송 시각을 넣으면 최대 60일 뒤까지 예약됩니다.

POST (딜러사 발송 API 주소)
X-Secret-Key: (발급받은 키)
{
  "senderKey": "(발신 키)",
  "templateCode": "ORDER_PAID",
  "recipientList": [{
    "recipientNo": "(받는 사람 번호)",
    "templateParameter": { "이름": "김OO", "주문번호": "A20261116-001" }
  }]
}

외부 API를 붙이는 일반 순서와 비용 요인은 API 연동, 진행 6단계와 외주 비용 요인 5가지와 같고, 아래는 알림톡에서 달라지는 부분입니다.

연동은 어떤 순서로 하나요

단계할 일맡는 쪽
1. 채널 준비카카오톡 채널을 비즈니스 채널로 전환, 홈 공개, 고객센터 정보 입력운영
2. 딜러사 계약채널을 발신 프로필로 등록하고 발신 키 · API 키 발급운영 · 개발
3. 템플릿 검수템플릿 등록 뒤 검수 요청. 영업일 기준 2일 안에 차례로 처리되고, 반려되면 고쳐 다시 요청운영
4. 발신번호 등록대체 발송에 쓸 번호를 문자 서비스에 등록운영
5. 서버 연동주문 · 예약 이벤트에서 템플릿 코드와 변수로 호출하고 응답의 요청 번호 저장개발
6. 시험 발송직원 번호로 보내 변수 자리와 대체 발송 상태 확인개발 · 운영

3단계 검수를 기다리는 동안 5단계 개발을 함께 진행해도 됩니다. 다만 반려되면 템플릿 코드나 변수 이름이 바뀔 수 있으니, 템플릿 코드와 변수 목록은 프로그램에 박지 말고 설정 표로 빼 두세요. 같은 딜러사 문서는 등록한 템플릿이 1년 동안 같은 상태로 있거나 발송이 없으면 휴면으로 바뀐다고 적고 있어, 가끔만 쓰는 템플릿은 상태를 주기적으로 확인합니다.

같은 주문에 알림이 두 번 가지 않게 하는 장치도 5단계에서 넣습니다. 이 딜러사 API는 중복 방지 키를 함께 보내면 10분 안에 같은 키로 들어온 요청을 실패 처리합니다. 주문번호와 템플릿 코드를 이은 값을 키로 쓰면 네트워크 오류로 다시 시도할 때 같은 알림이 두 번 나가지 않습니다.

템플릿 변수는 어떻게 설계하나요

고정 문장은 템플릿에 두고 바뀌는 값만 변수로 둡니다. 카카오 알림톡 심사 가이드는 변수 40개 초과, 변수로만 된 본문, 버튼명이나 미리보기 메시지에 넣은 변수를 반려 사유로 들고, 모든 변수에 예시 값을 적게 합니다. 프로그램에서 문장을 조합해 보내면 승인된 템플릿과 글자가 달라져 발송이 실패하므로(딜러사 결과 코드 "메시지 내용이 템플릿과 일치하지 않음"), 코드는 변수 값만 넘깁니다.

알림템플릿 고정 문장(예)변수예시 값버튼
주문 확인#{이름}님, 주문이 접수되었습니다. 주문번호 #{주문번호}, 결제 금액 #{결제금액}이름 · 주문번호 · 결제금액김OO · A20261116-001 · 32,000원주문 내역 보기
배송 시작#{이름}님이 주문하신 상품이 출발했습니다. #{택배사명} 운송장 #{운송장번호}이름 · 택배사명 · 운송장번호김OO · (택배 회사 이름) · (운송장 번호)배송 조회
예약 확정#{이름}님, #{예약일시} #{지점명} 예약이 확정되었습니다. 인원 #{인원}이름 · 예약일시 · 지점명 · 인원김OO · 12월 3일 오후 2시 · 강남점 · 2명예약 확인 · 변경

변수 값의 길이도 정해 둡니다. 같은 딜러사 결과 코드에 변수 글자 수 제한 초과가 따로 있어, 상품명처럼 길어질 수 있는 값은 몇 자에서 자를지 개발 전에 정합니다. 금액 · 날짜처럼 형식이 있는 값은 쉼표와 단위를 프로그램에서 붙여 넘깁니다.

실패와 대체 발송은 어떻게 처리하나요

대체 발송은 알림톡이 실패하면 같은 내용을 문자로 다시 보내는 기능입니다. 앞의 딜러사 API에서는 받는 사람마다 대체 발송 여부, 문자 종류(단문 SMS · 장문 LMS, 비우면 본문 길이로 결정), 대체 문구(비우면 알림톡 본문과 링크), 대체 발신번호를 넘깁니다. 문서에는 대체 발신번호가 문자 서비스에 등록된 번호가 아니면 실패할 수 있고, 대체 문구는 EUC-KR 기준으로 나가 지원하지 않는 이모티콘이 있으면 실패하며, 문자 종류별 이용료가 따로 붙는다고 적혀 있습니다. 대체 문구는 이모티콘 없이 따로 짧게 써 두세요.

결과 코드 설명원인처리
전화번호 오류번호 형식이 틀림회원 정보 저장 때 번호 형식 검사
메시지를 전송할 수 없음유심과 카카오톡 번호가 다름, 최근 7일 안에 카카오톡을 쓰지 않음 등문자로 대체 발송
카카오톡 유저가 아님카카오톡을 쓰지 않는 번호문자로 대체 발송
알림톡 수신 차단받는 사람이 차단문자로 대체 발송
템플릿을 찾을 수 없음 · 템플릿과 일치하지 않음템플릿 코드나 문구가 다름설정 표의 코드 · 변수 수정 뒤 다시 보내기
수신 확인이 안 됨(성공 불확실)3일 안에 받을 수 있는 상태다시 보내지 않음

발송 결과는 응답으로 받은 요청 번호로 조회 API를 불러 가져오고, 딜러사가 결과를 지정한 서버 주소로 보내 주는 웹훅을 제공하면 그쪽으로 받습니다. 결과에는 성공 · 실패와 함께 대체 발송 상태(대상 아님 · 대상 · 진행 중 · 성공 · 실패)를 저장해, 고객이 못 받았다고 할 때 어느 단계에서 끊겼는지 바로 찾게 하세요.

자주 묻는 질문

카카오에 직접 연동할 수는 없나요?

카카오비즈니스 가이드는 알림톡을 카카오와 파트너 계약을 맺은 공식 딜러사를 통해 진행한다고 안내합니다. 쓰는 쇼핑몰 · 예약 솔루션에 알림톡 기능이 들어 있다면 그 솔루션도 딜러사를 거쳐 보내는 구조이므로, 따로 개발하기 전에 솔루션 설정만으로 되는지 먼저 보세요.

승인된 템플릿을 고치면 코드도 바꿔야 하나요?

고친 템플릿은 다시 검수를 받습니다. 고정 문장만 바뀌고 템플릿 코드와 변수 이름이 그대로라면 프로그램은 손대지 않아도 됩니다. 새 템플릿으로 등록해 코드가 바뀌거나 변수 이름이 바뀌면 설정 표만 고치면 되도록, 템플릿 코드와 변수 목록을 프로그램 밖 설정으로 빼 두세요.

할인 · 이벤트 안내도 같은 API로 보내나요?

보내지 않습니다. 알림톡은 정보성 메시지만 보낼 수 있고, 광고성 메시지는 브랜드 메시지로 보냅니다. 한 발송 대행사 공지에 따르면 친구톡은 2025년 12월 31일로 끝났고, 2026년 1월부터 들어온 친구톡 발송 요청은 브랜드 메시지로 바뀌어 나갑니다. 광고는 수신 동의 확인과 광고 표기가 따로 필요하므로 호출 함수와 템플릿 목록을 알림톡과 나눠 두세요.

알림톡 연동을 외부에 맡기면 비용은 무엇으로 정해지나요?

자동으로 보낼 알림 수(템플릿 수), 알림을 일으키는 프로그램 수(쇼핑몰 · 예약 · 관리자 화면), 대체 발송과 결과 저장 범위, 관리자 화면에서 재발송 · 발송 기록 조회를 할지로 정해집니다. 알림 목록을 이벤트별로 정리해 알림톡 연동 개발 견적을 받으면 알림 하나를 더하거나 뺄 때 금액 차이를 바로 볼 수 있습니다.

오늘 할 일

주문 · 예약 이벤트마다 자동으로 보낼 알림과 그 알림에 들어갈 바뀌는 값을 목록으로 적어 보세요.

이어서 읽기 — 문자 발송 API, 발신번호 등록과 연동 순서 · 단가표

FacebookX

이 글과 맞는 서비스

이어서 읽기

블로그 전체 글 목록 →

카카오톡 상담식스원 고객센터 카카오톡 채널 (새 창)