---
title: "알림톡 메시지 발송"
method: POST
path: "/v2/messages/kakao/alim-talk"
tags: ["Kakao"]
---

# 알림톡 메시지 발송

`POST /v2/messages/kakao/alim-talk`

카카오 채널 추가 고객에게 사전 승인된 템플릿으로 정보성 메시지를 발송합니다.

## Request body

- object — 알림톡 발송을 위한 요청 정보입니다. 승인된 템플릿과 채널, 수신자 정보가 포함됩니다.
  - `sendProfileId` string, required — 채널 ID. 카카오 채널 관리자센터에서 등록한 채널의 ID입니다.
  - `templateId` string, required — 알림톡 템플릿 ID. 사전 검수 승인된 템플릿의 ID입니다.
  - `to` union[], required — 수신자 정보 목록. 최대 1,000명까지 동시 발송할 수 있습니다. - 변수 없는 경우: 휴대폰 번호 문자열 배열 ["01011112222", "01011113333"] - 변수 있는 경우: 객체 배열 [{phone: "01011112222", variables: {"#{고객명}": "홍길동"}}]
    - union
      - string — 메시지를 받을 수신자의 휴대폰 번호입니다. 하이픈(-) 없이 숫자만 입력해주세요.
      - object
        - `phone` string, required — 수신자 휴대폰 번호 (하이픈 없이 숫자만 입력)
        - `variables` object — 템플릿 변수 치환값 템플릿에 정의된 #{변수명} 형태의 변수에 대응하는 실제 값을 지정합니다. 변수명은 템플릿에 정의된 이름과 정확히 일치해야 합니다.
  - `reservation` object — 예약 발송 설정. 미입력시 즉시 발송됩니다.
    - `dateTime` string, date-time, nullable, required — 예약 발송 일시. 현재 시간 기준 10분 후부터 60일 이내로 설정할 수 있습니다.
  - `useCredit` boolean — 크레딧 우선 사용 여부. true 시 포인트보다 크레딧을 먼저 차감합니다.
  - `fallback` object — 대체문자 설정 카카오 메시지 수신 실패 시 SMS/LMS/MMS로 대체 발송합니다. - NONE: 대체문자 미사용 (기본값) - TEMPLATE: 템플릿에 설정된 대체문자 사용 - CUSTOM: 직접 지정한 대체문자 사용
    - `fallbackType` 'NONE' | 'TEMPLATE' | 'CUSTOM' — 대체문자 사용 옵션 - NONE: 대체문자 사용하지 않음 (기본값) - TEMPLATE: 템플릿에 설정된 대체문자 사용 (알림톡만 가능) - CUSTOM: 직접 설정한 대체문자 사용
    - `custom` object
      - `type` 'SMS' | 'LMS' | 'MMS', required — 대체문자 유형 - SMS: 80바이트 이내 텍스트 (제목/이미지 없음) - LMS: 2000바이트 이내 텍스트 (제목 선택) - MMS: 2000바이트 이내 텍스트+이미지 (제목 선택, 이미지 필수)
      - `senderNumber` string, required — 대체문자 발송에 사용할 발신번호입니다. 센드온에 사전 등록되고 승인된 발신번호만 사용할 수 있습니다.
      - `isAd` boolean — 광고성 메시지 여부입니다. 광고성 메시지는 관련 법규에 따라 수신자의 사전 동의가 필요합니다.
      - `message` string, required — 대체문자 내용. 알림톡 수신 실패 시 발송될 메시지입니다. SMS는 80바이트, LMS/MMS는 2000바이트 제한.
      - `title` string — 메시지 제목. LMS/MMS 타입에서만 사용할 수 있습니다. 40바이트 제한.
      - `images` string[] — 이미지 URL 배열. MMS 타입에서만 사용할 수 있습니다. 최대 3개까지 첨부할 수 있습니다.

## Response `200`

알림톡 발송 요청의 처리 결과입니다. 성공 시 발송 상태 추적을 위한 그룹 ID가 포함됩니다.

- object — 알림톡 발송 요청의 처리 결과입니다. 성공 시 발송 상태 추적을 위한 그룹 ID가 포함됩니다.
  - `code` 200, required — 응답 코드
  - `message` string — 응답 메시지
  - `data` object, required — 발송 요청 성공 시 반환되는 데이터
    - `groupId` string, required — 메시지 발송 요청이 성공적으로 처리되어 생성된 그룹의 ID입니다. 이 UUID 형식의 ID로 발송 상태를 추적하고 결과를 조회할 수 있습니다.

## Other responses

- `400` — 잘못된 요청 - 필수 파라미터 누락, 잘못된 형식, 또는 유효하지 않은 값
- `401` — 인증 실패 - API 키가 유효하지 않거나 만료됨
- `403` — 권한 없음 - 크레딧 부족, 채널 미인증, 또는 템플릿 미승인
- `404` — 리소스 없음 - 템플릿 또는 채널을 찾을 수 없음
- `429` — 요청 제한 초과 - Rate limit에 도달함
- `500` — 서버 오류 - 내부 오류 또는 외부 API 장애

---

[API](https://skmtc.net/sendon/apis/sendon-api.md) · [All operations](https://skmtc.net/sendon/apis/sendon-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sendon/sendon-api/versions/525dedc81a05/schema)