알림톡 템플릿 자동치환 발송, 본문 없이 템플릿 코드만으로 보내는 법

2026-05-01

비즈고 알림톡 API에 자동치환 발송이 추가됐어요. 이번 글에서는 자동치환 발송이 정확히 무엇인지, 왜 필요한지, 어떻게 호출하는지 정리했어요. 자세한 API 레퍼런스는 비즈고 개발자센터에서 확인할 수 있어요.

🔍 자동치환 발송이란?

템플릿 코드와 변수 값으로 알림톡 발송이 완성되는 자동치환 발송 개념 도식

자동치환 발송은 메시지 본문을 입력할 필요 없이 템플릿 코드와 변수 값만으로 알림톡을 발송하는 방식이에요. 이번에 사용할 템플릿 코드와 변수 값만 지정하면 메시지가 자동 치환되어 발송됩니다.

🤔 자동치환 발송이 왜 필요할까?

알림톡은 본문이 등록 템플릿과 다르면 발송이 실패해요. 띄어쓰기, 줄바꿈, 특수기호가 등록 템플릿과 어긋나도 발송이 안 되죠. 그래서 발송 코드를 짤 때 등록 템플릿 본문을 정확히 옮겨 담는 작업이 필요했고, 본문 텍스트를 코드 안에 유지보수하는 부담도 따라왔습니다.

자동치환 발송에서는 비즈고 API가 카카오톡 비즈메시지 채널에 등록된 템플릿의 본문을 가져와 알림톡을 발송해요. 발송 코드에는 templateCode만 입력하면 되니까 본문 텍스트를 직접 다룰 일 자체가 없습니다. 본문 불일치로 발송이 실패할 가능성이 줄어들고, 본문 텍스트를 코드 안에 따로 관리할 필요도 없어집니다.

💻 자동치환 발송 호출 방법

자동치환 발송은 비즈고 알림톡 API의 옴니 메시지 발송 엔드포인트(POST /api/comm/v1/send/omni)를 그대로 사용해요. 기존 발송과 같은 엔드포인트지만 페이로드 구성이 달라집니다.

구분	기존 발송	자동치환 발송
본문(text)	직접 입력해서 전송	입력 불필요
sendType	미사용	"template" 지정

① 핵심 파라미터

자동치환 발송 호출에 필요한 주요 파라미터는 다음과 같아요.

sendType: “template” 입력. 자동치환 모드 신호예요.
senderKey: 카카오톡 비즈메시지 발신프로필 키
templateCode: 카카오톡 비즈메시지 채널에 등록된 템플릿 코드
replaceWords: 변수 치환 객체. 수신자별로 다른 값을 넣을 수 있어요.
text: 입력 불필요

destinations 배열에는 수신번호(to)와 함께 replaceWords를 넣어요. 한 번의 호출로 여러 수신자에게 각자 다른 변수 값을 채워 발송할 수 있습니다.

② 호출 예시

cURL로 자동치환 발송을 호출하는 예시입니다.

cURL Request
curl -X POST "https://mars.ibapi.kr/api/comm/v1/send/omni" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
    "destinations": [{
      "to": "01000000000",
      "replaceWords": {
        "name": "홍길동",
        "orderName": "비즈고 이용권",
        "status": "결제완료"
      }
    }],
    "messageFlow": [{
      "alimtalk": {
        "senderKey": "{senderKey}",
        "templateCode": "{templateCode}",
        "sendType": "template"
      }
    }],
    "ref": "alimtalk-template-001"
  }'

③ 호출 흐름

위 페이로드를 비즈고 API로 전송하면 다음 흐름으로 발송이 진행돼요.

클라이언트가 templateCode와 replaceWords를 비즈고 API에 전송
비즈고 API가 templateCode에 맞는 등록 템플릿을 조회
템플릿 본문의 변수 자리(#{name}, #{orderName} 등)를 replaceWords 값으로 치환
완성된 알림톡을 수신번호로 발송

알림톡 API 연동이 처음이면 알림톡 API 연동 가이드에서 채널 개설부터 발신프로필 키 발급까지 기본 흐름을 먼저 확인하면 됩니다.

💡 자동치환 발송 사용 전 알아두면 좋은 점

자동치환 발송을 도입하기 전 확인하면 좋은 점들을 정리했어요.

별도 템플릿 등록 없이 기존 템플릿을 그대로 사용해요

자동치환 발송은 호출 방식만 달라지는 거라 자동치환 발송용 템플릿을 따로 등록할 필요는 없어요. 채널과 템플릿 등록은 기존 알림톡 발송과 동일한 절차로 진행하시면 되고, 이미 사용 중인 템플릿이 있다면 그대로 자동치환 발송에 활용하실 수 있습니다.

변수가 없는 템플릿도 자동치환 발송이 가능합니다

변수 없이 고정 본문만 있는 템플릿이라면 replaceWords 없이 templateCode만으로 발송할 수 있어요. 변수가 있는 템플릿에만 replaceWords가 필수예요.

비즈고 샌드박스에서 비용 차감 없이 테스트할 수 있어요

비즈고 개발자센터의 샌드박스에서 자동치환 발송 페이로드를 그대로 호출해 응답 흐름을 확인할 수 있습니다. 실제 발송이 아니라 비용도 차감되지 않고, 본인 번호로 반복 호출할 필요도 없어요. 메시지 API 도입을 검토 중이라면 메시지 API 도입 전 체크리스트도 함께 보면 좋아요.