> For the complete documentation index, see [llms.txt](https://docs.groobee.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.groobee.ai/new-admin/kakao-alimtalk/kakao-alimtalk-create/api-trigger.md).
# API 트리거 발송
외부 API 요청을 통해 **원하는 시점에 특정 고객에게 메시지를 실시간으로 보내는 방식**입니다.
고객사의 자체 시스템(CRM, 주문/재고 관리 등)의 이벤트와 연동하여 맞춤형 메시지를 발송할 수 있습니다. (예: 품절 상품 재입고 알림, 주문 상태 변경 안내)
{% hint style="warning" %}
메시지 구성 요소별 [**발송 가능 최대 글자 수**](https://docs.groobee.ai/~/changes/276/new-admin/kakao-alimtalk/kakao-alimtalk-create/api-trigger#id-2-1)를 고려하여 API를 요청해 주세요.
{% endhint %}
## **1단계: 기본 설정**
* **캠페인명:** 캠페인의 이름을 입력해 주세요. (문자 구분 없이 최대 40자 입력 가능)
* **상세 설명:** 필요시 캠페인에 대한 상세 설명을 입력해 주세요. (문자 구분 없이 최대 400자 입력 가능)
* **태그 #:** 캠페인에 태그를 설정해 주세요. 캠페인 리스트에서 태그 필터를 통해 캠페인을 필터링할 때 활용됩니다.
***
## **2단계: 메시지 설정**
### **1. 템플릿 선택**
캠페인에 사용할 템플릿을 선택해 주세요. 템플릿은 검수가 완료된 **승인 상태의 템플릿**만 선택할 수 있습니다.
### **2. 템플릿 정보**
선택한 템플릿에 설정된 상세 정보를 확인할 수 있습니다.
* **기본 설정:** 템플릿의 이름, 코드, 카테고리와 같은 기본 정보를 보여줍니다.
* **개인화 설정:** 메시지에 사용된 개인화 변수의 목록을 보여줍니다.
* **템플릿 메시지:** 실제 발송될 메시지의 제목, 본문, 버튼 등의 내용을 보여줍니다.
* **미리보기:** 알림톡 메시지가 사용자에게 어떻게 보일지 미리 확인할 수 있습니다.
메시지 구성 요소별 발송 가능 최대 글자 수
| 구성 요소 | 발송 가능 최대 글자 수 |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **강조 표기형 > 제목** | 50자 |
| **강조 표기형 > 부제목** | 18자 |
| **메시지 본문** |
카카오톡 25.8.0 버전 이상 사용자: 1,300자
카카오톡 25.8.0 버전 미만 사용자: 1,000자
|
| **버튼 > 링크** |
모바일: 920자
PC: 920자
Android: 1,000자
iOS: 1,000자
|
{% hint style="info" %}
미리보기는 **참고용으로 제공**되며, 실제 메시지는 수신자의 기기나 앱 환경에 따라 다르게 보일 수 있습니다.
{% endhint %}
***
## **3단계: 옵션 설정**
### **1. 스케줄 설정**
캠페인이 진행될 기간을 설정해 주세요.
* **수동 종료 전까지:** 직접 종료하기 전까지 캠페인이 계속 진행됩니다.
* **기간 지정:** 시작일과 종료일을 미리 설정하여, 해당 기간 내에만 캠페인이 진행됩니다.
{% hint style="warning" %}
캠페인은 저장 후 **진행중**으로 상태를 변경해야 설정한 시간에 맞춰 진행됩니다.
{% endhint %}
### **2. 코드 샘플**
API를 통해 알림톡을 발송할 때 사용하는 코드 예시입니다. 아래 설명을 참고하여 개발팀과 소통 후 알림톡 발송을 요청해 주세요.
* **캠페인 키:** 캠페인마다 부여되는 고유 ID입니다. 이 키를 통해 발송할 캠페인이 식별되므로, API 요청 시 필수로 포함해 주세요.
* **메시지 발송 대상:** 메시지를 수신할 대상을 지정하는 값으로, **phoneNumber, appUserId, userKey** 중 하나를 선택하여 요청해 주세요.
* **개인화 데이터:** 템플릿에 개인화 변수(예: #{name})를 사용한 경우, 각 변수에 치환될 실제 값을 담아 요청해 주세요. 치환 값이 없으면 설정된 대체 값으로 발송됩니다.
응답 코드
| type | code | message | httpStatus | httpStatusCode |
| ---- | ---- | ------------------------------------------ | ----------------------- | -------------- |
| 성공 | 0 | 성공 | OK | 200 |
| 헤더 | 1101 | x-api-key 헤더가 누락되었습니다. | BAD\_REQUEST | 400 |
| 헤더 | 1102 | Content-Type 헤더가 누락되었습니다. | BAD\_REQUEST | 400 |
| 일반 | 1201 | 요청 본문에 내용이 없습니다. | BAD\_REQUEST | 400 |
| 일반 | 1202 | 요청 데이터 행이 너무 많습니다. | BAD\_REQUEST | 400 |
| 일반 | 1203 | 요청 포맷이 잘못되었습니다. | BAD\_REQUEST | 400 |
| 일반 | 1204 | 올바르지 않은 날짜 형식입니다. | BAD\_REQUEST | 400 |
| 인증 | 1401 | API 키가 유효하지 않습니다. | UNAUTHORIZED | 401 |
| 인증 | 1402 | API 사용권한이 없습니다. | UNAUTHORIZED | 401 |
| 인증 | 1403 | 등록되지 않은 회원사 | UNAUTHORIZED | 401 |
| 인증 | 1404 | 미승인 회원사 | UNAUTHORIZED | 401 |
| 인증 | 1405 | 만료된 회원사 | UNAUTHORIZED | 401 |
| 기타 | 2000 | 내부 서버 에러 | INTERNAL\_SERVER\_ERROR | 500 |
| 알림톡 | 7001 | 채널 연동 필요 | BAD\_REQUEST | 400 |
| 알림톡 | 7002 | 발신프로필이 차단 되었습니다. | BAD\_REQUEST | 400 |
| 알림톡 | 7003 | 발신프로필이 휴면 상태입니다. | BAD\_REQUEST | 400 |
| 알림톡 | 7004 | 해당 캠페인의 템플릿이 대기 상태입니다. | BAD\_REQUEST | 400 |
| 알림톡 | 7005 | 해당 캠페인의 템플릿이 검수 요청 상태입니다. | BAD\_REQUEST | 400 |
| 알림톡 | 7006 | 해당 캠페인의 템플릿이 휴면 상태입니다. | BAD\_REQUEST | 400 |
| 알림톡 | 7007 | 해당 캠페인의 템플릿이 차단 상태입니다. | BAD\_REQUEST | 400 |
| 알림톡 | 7008 | 해당 캠페인의 템플릿이 중지 상태입니다. | BAD\_REQUEST | 400 |
| 알림톡 | 7009 | 해당 캠페인의 템플릿이 검수 반려 상태입니다. | BAD\_REQUEST | 400 |
| 알림톡 | 7010 | 해당 캠페인의 템플릿이 만료 상태입니다. | BAD\_REQUEST | 400 |
| 알림톡 | 7011 | 발송을 위한 필수 파라미터가 누락 되었습니다. | BAD\_REQUEST | 400 |
| 알림톡 | 7012 | 전달하신 전화번호 길이가 12자가 아닙니다. | BAD\_REQUEST | 400 |
| 알림톡 | 7997 | 카카오 알림톡 발송 단가가 적용되지 않았습니다. - 그루비에 문의해 주세요. | BAD\_REQUEST | 400 |
| 알림톡 | 7998 | 카카오 발송 API call error - 그루비에 문의해 주세요. | INTERNAL\_SERVER\_ERROR | 500 |
| 알림톡 | 7999 | 내부 서버 에러 | INTERNAL\_SERVER\_ERROR | 500 |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.groobee.ai/new-admin/kakao-alimtalk/kakao-alimtalk-create/api-trigger.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.