---
updatedAt: 2026-08-27T04:52:17.000Z
agentTools:
projectIndex: https://sdk.sendon.io/llms.txt
---
# 알림톡 메시지 발송
카카오 채널 추가 고객에게 사전 승인된 템플릿으로 정보성 메시지를 발송합니다.
센드온 API는 네트워크 에러를 분리하기 위해 HTTP 상태 코드 200으로 응답합니다.
자세한 응답 코드는 [API 응답 코드 가이드](https://sdk.sendon.io/reference/4-api-%EC%9D%91%EB%8B%B5-%EC%BD%94%EB%93%9C-%EA%B0%80%EC%9D%B4%EB%93%9C#/) 를 참고해주세요.
- 채널과 템플릿은 사전에 등록해야합니다.
- 정보성 메시지만 발송 가능합니다.
알림톡은 카카오톡 채널을 통해 고객에게 정보성 메시지를 발송할 수 있는 비즈니스 메시징 서비스입니다.
사전에 승인된 템플릿을 기반으로 발송되며, 문자 메시지보다 풍부한 콘텐츠와 높은 도달률을 제공합니다.
## 알림톡 발송 전 필수 준비사항
알림톡을 발송하기 위해서는 다음 사항이 필요합니다:
1. 카카오 비즈니스 채널 생성 및 연동
2. 알림톡 템플릿 등록 및 승인 완료
3. 채널 ID 확인
4. 템플릿 ID 확인
## 대체 발송
대체발송(Fallback)은 카카오 알림톡이나 친구톡 발송이 실패할 경우 자동으로 SMS, LMS, MMS 등 일반 문자메시지로 전환하여 발송하는 기능입니다. 이 기능을 통해 메시지 전달의 신뢰성을 높이고 다양한 상황에서 메시지가 수신자에게 도달할 수 있도록 보장할 수 있습니다.
### 대체발송이 필요한 상황
* 수신자가 카카오톡을 사용하지 않는 경우
* 수신자가 카카오톡 알림을 차단한 경우
* 수신자가 비즈니스 채널과 친구 관계가 아닌 경우 (친구톡)
* 카카오톡 서버 오류 등으로 발송이 실패한 경우
### 대체발송 유형
센드온 SDK에서는 다음과 같은 대체발송 유형을 지원합니다:
1. **SMS (Short Message Service)**
* 최대 90바이트 이내의 짧은 텍스트 메시지
* 제목이나 이미지를 포함할 수 없음
2. **LMS (Long Message Service)**
* 최대 2,000바이트 이내의 긴 텍스트 메시지
* 제목 포함 가능
3. **MMS (Multimedia Message Service)**
* 텍스트 메시지와 함께 이미지를 포함
* 제목 포함 가능
* 이미지는 최대 3장까지 첨부 가능
* 메시지가 짧아도 이미지가 첨부되면 MMS로 분류됨
## 대체발송 설정 방법
### 대체발송 설정 옵션
대체발송 설정은 `fallback` 객체를 통해 지정하며, 다음과 같은 옵션을 제공합니다:
| 옵션 | 설명 | 적용 가능 메시지 |
| -------- | -------------------- | --------- |
| NONE | 대체발송을 사용하지 않음 (기본값) | 알림톡, 친구톡 |
| TEMPLATE | 템플릿에 설정된 대체발송 내용을 사용 | 알림톡만 가능 |
| CUSTOM | 직접 설정한 대체발송 내용을 사용 | 알림톡, 친구톡 |
> **참고**: `fallback` 파라미터를 설정하지 않으면 대체발송이 이루어지지 않습니다.
### TEMPLATE 옵션 설명
TEMPLATE 옵션은 알림톡에만 사용 가능한 기능으로, 센드온 플랫폼에서 템플릿을 등록할 때 미리 설정한 대체발송 내용을 활용합니다.
* 센드온 플랫폼에서 알림톡 템플릿 등록 시 함께 설정한 대체발송 내용을 그대로 사용
* 별도로 대체발송 내용을 작성할 필요 없이 템플릿에 설정된 내용을 일관되게 활용 가능
* 템플릿 변경 시 대체발송 내용도 함께 관리되므로 유지보수가 용이
* 템플릿에 대체발송 내용이 설정되어 있지 않은 경우 사용 불가
## 대체발송 파라미터
### 기본 파라미터
| 파라미터 | 타입 | 설명 | 필수 여부 |
| --------------------- | ------ | -------------------------------------- | ----- |
| fallback | object | 대체발송 설정 객체 | 선택 |
| fallback.fallbackType | string | 대체발송 유형 ('NONE', 'TEMPLATE', 'CUSTOM') | 필수 |
### CUSTOM 옵션 사용 시 파라미터
| 파라미터 | 타입 | 설명 | 필수 여부 |
| ---------------------------- | --------- | ----------------------------- | ------------ |
| fallback.custom | object | 대체발송 상세 설정 | CUSTOM 타입 필수 |
| fallback.custom.type | string | 대체문자 유형 ('SMS', 'LMS', 'MMS') | 필수 |
| fallback.custom.senderNumber | string | 발신번호 (센드온에 등록된 번호) | 필수 |
| fallback.custom.message | string | 메시지 내용 | 필수 |
| fallback.custom.isAd | boolean | 광고성 메시지 여부 | 필수 |
| fallback.custom.title | string | 메시지 제목 | LMS/MMS 선택 |
| fallback.custom.images | string\[] | 이미지 ID 배열 | MMS 필수 |
## 대체발송 이미지 업로드
MMS 대체발송을 사용하려면 먼저 이미지를 업로드해야 합니다. [대체문자 이미지 파일 업로드](https://sdk.sendon.io/v0.9.3/reference/uploadfallbackimage#/) API를 사용하여 가능합니다.
## 주의사항
1. **대체발송 처리 시점**
* 대체문자는 카카오 메시지 발송 처리가 완료된 후, 미발송된 메시지에 대한 포인트가 환급된 이후에 발송됩니다.
2. **포인트 차감**
* 대체발송 시 알림톡/친구톡 포인트와 별도로 문자 메시지 발송에 필요한 포인트가 차감됩니다.
* 이로 인해 최초 포인트 차감액보다 더 많은 포인트가 차감될 수 있습니다.
3. **포인트 부족**
* 대체발송에 필요한 포인트가 부족한 경우 대체발송이 취소될 수 있습니다.
4. **광고성 표시**
* 광고성 메시지의 경우 `isAd` 값을 `true`로 설정해야 합니다.
* 광고성 메시지는 관련 법규를 준수해야 합니다.
5. **문자 길이 제한**
* SMS: 90바이트 이내
* LMS: 2,000바이트 이내
* 바이트 계산 시 한글은 일반적으로 2\~3바이트를 차지합니다.
6. **인코딩 차이**
* 카카오 메시지는 UTF-8 인코딩을 사용하고, 대체발송 문자는 EUC-KR 인코딩을 사용합니다.
* 이 차이로 인해 이모티콘이나 일부 특수 문자가 대체발송 문자에서 정상적으로 출력되지 않을 수 있습니다.
* 대체문자 설정 시 문자가 의도하지 않은 형태로 표시되지 않는지 확인하는 것이 좋습니다.
7. **발신번호 등록**
* 대체발송에 사용되는 발신번호(senderNumber)는 센드온 계정에 사전 등록되고 승인된 번호여야 합니다.
8. **이미지 제한**
* MMS 발송 시 이미지는 총 3개까지 첨부 가능합니다.
* 메시지 내용이 짧아도 이미지가 첨부되면 MMS로 분류됩니다.
9. **템플릿 대체발송 제한**
* `TEMPLATE` 옵션은 알림톡에서만 사용 가능합니다.
* 친구톡에서는 `CUSTOM` 옵션만 사용할 수 있습니다.
# OpenAPI definition
```json
{
"openapi": "3.0.0",
"paths": {
"/v2/messages/kakao/alim-talk": {
"post": {
"operationId": "MessageController_sendAlimTalk",
"summary": "알림톡 메시지 발송",
"description": "카카오 채널 추가 고객에게 사전 승인된 템플릿으로 정보성 메시지를 발송합니다.",
"parameters": [],
"requestBody": {
"required": true,
"description": "알림톡 발송을 위한 요청 정보입니다. 승인된 템플릿과 채널, 수신자 정보가 포함됩니다.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SendAlimTalkRequestDto"
}
}
}
},
"responses": {
"200": {
"description": "알림톡 발송 요청의 처리 결과입니다. 성공 시 발송 상태 추적을 위한 그룹 ID가 포함됩니다.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SendAlimTalkResponseDto"
}
}
}
},
"400": {
"description": "잘못된 요청 - 필수 파라미터 누락, 잘못된 형식, 또는 유효하지 않은 값"
},
"401": {
"description": "인증 실패 - API 키가 유효하지 않거나 만료됨"
},
"403": {
"description": "권한 없음 - 크레딧 부족, 채널 미인증, 또는 템플릿 미승인"
},
"404": {
"description": "리소스 없음 - 템플릿 또는 채널을 찾을 수 없음"
},
"429": {
"description": "요청 제한 초과 - Rate limit에 도달함"
},
"500": {
"description": "서버 오류 - 내부 오류 또는 외부 API 장애"
}
},
"tags": [
"Kakao"
],
"security": [
{
"basic": []
}
]
}
}
},
"info": {
"title": "Sendon API",
"description": "Sendon API Generated on 2026-08-27T02:12:51.075Z",
"version": "v2",
"contact": {
"name": "센드온",
"url": "https://console.sendon.io/",
"email": ""
},
"license": {
"name": "서비스 이용약관",
"url": "https://olive-challenge-eca.notion.site/1a43c16d2709804e9de1dd81e0abf477"
}
},
"servers": [
{
"url": "https://api.sendon.io/",
"description": "prd"
}
],
"components": {
"securitySchemes": {
"basic": {
"type": "http",
"scheme": "basic"
}
},
"schemas": {
"MessageReservationDto": {
"type": "object",
"properties": {
"dateTime": {
"type": "string",
"description": "예약 발송 일시. 현재 시간 기준 10분 후부터 60일 이내로 설정할 수 있습니다.",
"example": "2024-01-15T14:30:00Z"
},
"datetime": {
"type": "string",
"description": "내부 호환 예약 발송 시각",
"example": "2026-03-07T09:00:00+09:00"
}
}
},
"SendAlimTalkRequestDto": {
"type": "object",
"properties": {
"sendProfileId": {
"type": "string",
"description": "채널 ID. 카카오 채널 관리자센터에서 등록한 채널의 ID입니다.",
"example": "@test1234"
},
"templateId": {
"type": "string",
"description": "알림톡 템플릿 ID. 사전 검수 승인된 템플릿의 ID입니다.",
"example": "TEMPLATE1234567890"
},
"to": {
"type": "array",
"description": "수신자 정보 목록. 최대 1,000명까지 동시 발송할 수 있습니다.\n- 변수 없는 경우: 휴대폰 번호 문자열 배열 [\"01011112222\", \"01011113333\"]\n- 변수 있는 경우: 객체 배열 [{phone: \"01011112222\", variables: {\"#{고객명}\": \"홍길동\"}}]",
"example": [
"01011112222",
{
"phone": "01011113333",
"variables": {
"#{고객명}": "김철수",
"#{주문번호}": "20240115001"
}
}
],
"minItems": 1,
"maxItems": 1000,
"items": {
"oneOf": [
{
"type": "string",
"description": "메시지를 받을 수신자의 휴대폰 번호입니다. 하이픈(-) 없이 숫자만 입력해주세요.",
"example": "01011112222"
},
{
"type": "object",
"properties": {
"phone": {
"type": "string",
"description": "수신자 휴대폰 번호 (하이픈 없이 숫자만 입력)",
"example": "01011112222"
},
"variables": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "템플릿 변수 치환값\n\n템플릿에 정의된 #{변수명} 형태의 변수에 대응하는 실제 값을 지정합니다.\n변수명은 템플릿에 정의된 이름과 정확히 일치해야 합니다.",
"example": {
"#{고객명}": "홍길동",
"#{주문번호}": "1234567890",
"#{배송예정일}": "2024-01-15"
}
}
},
"required": [
"phone"
]
}
]
}
},
"useCredit": {
"type": "boolean",
"description": "크레딧 우선 사용 여부. true 시 포인트보다 크레딧을 먼저 차감합니다.",
"default": true,
"example": true
},
"reservation": {
"description": "예약 발송 설정. 미입력시 즉시 발송됩니다.",
"allOf": [
{
"$ref": "#/components/schemas/MessageReservationDto"
}
]
},
"fallback": {
"type": "object",
"description": "대체문자 설정\n\n카카오 메시지 수신 실패 시 SMS/LMS/MMS로 대체 발송합니다.\n- NONE: 대체문자 미사용 (기본값)\n- TEMPLATE: 템플릿에 설정된 대체문자 사용\n- CUSTOM: 직접 지정한 대체문자 사용",
"example": {
"fallbackType": "CUSTOM",
"custom": {
"type": "SMS",
"senderNumber": "01011112222",
"isAd": true,
"message": "안녕하세요. 고객님의 주문이 확정되었습니다."
}
},
"properties": {
"fallbackType": {
"type": "string",
"default": "NONE",
"enum": [
"NONE",
"TEMPLATE",
"CUSTOM"
],
"description": "대체문자 사용 옵션\n- NONE: 대체문자 사용하지 않음 (기본값)\n- TEMPLATE: 템플릿에 설정된 대체문자 사용 (알림톡만 가능)\n- CUSTOM: 직접 설정한 대체문자 사용",
"example": "CUSTOM"
},
"custom": {
"type": "object",
"required": [
"type",
"senderNumber",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"SMS",
"LMS",
"MMS"
],
"description": "대체문자 유형\n- SMS: 80바이트 이내 텍스트 (제목/이미지 없음)\n- LMS: 2000바이트 이내 텍스트 (제목 선택)\n- MMS: 2000바이트 이내 텍스트+이미지 (제목 선택, 이미지 필수)"
},
"senderNumber": {
"type": "string",
"description": "대체문자 발송에 사용할 발신번호입니다. 센드온에 사전 등록되고 승인된 발신번호만 사용할 수 있습니다.",
"example": "01011112222"
},
"isAd": {
"type": "boolean",
"default": true,
"description": "광고성 메시지 여부입니다. 광고성 메시지는 관련 법규에 따라 수신자의 사전 동의가 필요합니다.",
"example": true
},
"message": {
"type": "string",
"description": "대체문자 내용. 알림톡 수신 실패 시 발송될 메시지입니다. SMS는 80바이트, LMS/MMS는 2000바이트 제한.",
"example": "안녕하세요. 고객님의 주문이 접수되었습니다."
},
"title": {
"type": "string",
"description": "메시지 제목. LMS/MMS 타입에서만 사용할 수 있습니다. 40바이트 제한.",
"example": "주문 확인"
},
"images": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 3,
"description": "이미지 URL 배열. MMS 타입에서만 사용할 수 있습니다. 최대 3개까지 첨부할 수 있습니다.",
"example": [
"https://example.com/image1.jpg",
"https://example.com/image2.jpg"
]
}
}
}
}
}
},
"required": [
"sendProfileId",
"templateId",
"to"
]
},
"MessageSendResultDto": {
"type": "object",
"properties": {
"groupId": {
"type": "string",
"description": "메시지 발송 요청이 성공적으로 처리되어 생성된 그룹의 ID입니다. 이 UUID 형식의 ID로 발송 상태를 추적하고 결과를 조회할 수 있습니다.",
"example": "004a6217-f06c-40f6-8f39-bf35b3f76111"
}
},
"required": [
"groupId"
]
},
"SendAlimTalkResponseDto": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "HTTP 상태 코드입니다. 200이면 성공, 400대는 클라이언트 오류, 500대는 서버 오류를 나타냅니다.",
"example": 200
},
"message": {
"type": "string",
"description": "API 호출 결과에 대한 사람이 읽을 수 있는 메시지입니다. 성공 시 \"OK\", 실패 시 구체적인 오류 사유가 포함됩니다.",
"example": "OK"
},
"data": {
"description": "발송 요청 성공 시 반환되는 데이터입니다.",
"allOf": [
{
"$ref": "#/components/schemas/MessageSendResultDto"
}
]
}
},
"required": [
"code",
"message",
"data"
]
}
}
}
}
```