사이드 메뉴
커뮤니케이션
API 제공
어드민 API
문자 메시지
REST API
이 문서는 문자 메시지 REST API 사용 방법을 안내합니다.
| 페이즈 | 호스트 |
|---|---|
| 샌드박스(Sandbox) | http://kims-api.dev.9rum.cc |
| 프로덕션(Production) | https://kims-api.kakao.com |
페이즈 사용 용도
샌드박스 페이즈는 테스트 용도로만 사용해야 합니다.
문자 메시지 발송을 요청합니다.
헤더에 서비스 앱 어드민 키를 담아 POST로 요청합니다. 문자 메시지 타입을 경로 변수에 전달해야 합니다.
문자 메시지 API는 동보 발송을 지원하므로 한 번에 최대 1,000건의 문자 메시지 발송을 요청할 수 있습니다.
동보 발송이란?
하나의 송신 장치에서 여러 개의 수신 장치로 동시에 같은 내용의 정보를 보내는 통신 방법입니다.
요청 성공 시 응답은 발송 요청 ID와 발송 요청된 문자 메시지 정보를 포함합니다. 문자 메시지 발송 요청의 결과는 응답에 포함되지 않습니다. 발송 결과 알림을 설정해 서비스 서버로 문자 메시지 발송 요청의 결과를 전달받아야 합니다. 또는 요청 ID로 발송 결과 조회, 문자 메시지 ID로 발송 결과 조회 API로 발송 결과를 확인할 수 있습니다.
요청 실패 시 에러 코드로 원인을 확인합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}인증 방식, 서비스 앱 어드민 키로 인증 요청 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| TYPE | String | 발송 형식 타입, 아래 중 하나
| O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| caller_number | String | 발신번호 하이픈( -) 없이 숫자만 입력(예: 15773754)중요: 국내 발송 시 필수 | X |
| type | String | 발송 목적 타입 타입별 메시지 내용 규격 준수 필요, 아래 중 하나
NORMAL) | X |
| country_code | String | 수신번호의 국제전화 국가 번호 더하기표( +) 없이 숫자만 입력(기본값: 82)국내 발송만 가능한 LMS 또는 MMS의 경우, country_code 값이 82가 아니면 요청 실패 처리 | X |
| subject | String | 문자 메시지 제목EUC-KR 인코딩된 문자열(최대: 40 Byte) 중요: LMS, MMS인 경우에만 사용 | X |
| receivers | Receiver[] | 문자 메시지 정보 수신번호와 문자 메시지 내용을 담은 목록 (최대: 1,000건) | O |
| files | File[] | 첨부 파일을 담은 목록 (최대: 3개) 중요: MMS인 경우 필수, 파일 첨부 순서대로 단말 도착을 보장할 수 없음 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| receiver_number | String | 국제전화 국가 번호를 제외한 수신번호 중요: receiver_number 사용 시 country_code 값을 필수 전달해야 하며, full_receiver_number 값은 무시됨 | O* |
| full_receiver_number | String | 국제전화 국가 번호를 포함한 수신번호 중요: full_receiver_number 사용 시 country_code 값은 무시됨(예: 821000000000) | O* |
| content | String | 문자 메시지 내용, 아래 규격 준수 필요 SMS: 국내 발송 시 EUC-KR 인코딩된 문자열(최대 90 Byte), 국제 발송 시 UTF-8 인코딩된 문자열(최대 1,000 Byte)LMS, MMS: EUC-KR 인코딩된 문자열(최대 2,000 Byte)중요: 국제 발송 시 특수문자 사용을 권장하지 않음, 통신사별 인코딩 방식이 상이해 특수문자가 글자 수나 발송 결과에 영향을 미칠 수 있음 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| name | String | 파일 이름, 확장자 포함, UTF-8 인코딩된 문자열(최대: 50 Byte, 예: name.jpg) | O |
| body | String | 원본 이미지를 Base64 인코딩한 문자열 원본 이미지는 아래 규격을 따라야 함 가로: 1,000 픽셀 이하 세로: 1,000 픽셀 이하 파일 용량: 300 KB 이하 파일 형식: jpg, jpeg | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| request_id | String | 발송 요청 ID 요청 ID로 발송 결과 조회 API 요청 시 사용 | O |
| messages | Message[] | 발송 요청된 문자 메시지 정보 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| message_id | Long | 문자 메시지 ID 문자 메시지 ID로 발송 결과 조회 API 요청 시 사용 | O |
| type | String | 발송 형식 타입, 아래 중 하나
| O |
| country_code | String | 수신번호의 국제전화 국가 번호 | O |
| receiver_number | String | 국제전화 국가 번호를 제외한 수신번호 | O |
| caller_number | String | 발신번호 | X |
| subject | String | 문자 메시지 제목 | X |
| content | String | 문자 메시지 내용 | O |
| file_names | String[] | MMS인 경우, 첨부된 파일의 이름 배열 | X |
| status_code | String | 발송 요청의 상태 코드, 아래 중 하나
| O |
| status_msg | String | 발송 요청의 상태 설명 | O |
| result_code | String | 개별 문자 메시지 발송 결과에 대한 결과 코드 | X |
| result_msg | String | 개별 문자 메시지 발송 결과 설명 | X |
| report_date | String | 이동통신사 또는 중계사로부터 결과를 전달받은 일시, 한국 표준시(KST) 시간대로 고정된 ISO8601 형식(예: 2024-06-13T15:25:47+09:00) | X |
| 결과 코드 | 분류 | 설명 | 상태 코드 |
|---|---|---|---|
M000 | 대기 | 문자 메시지 발송 대기 | READY |
M001 | 대기 | 문자 메시지 발송 결과 대기 | SENT |
M004 | 실패 | 문자 메시지 발송 요청 전달 실패 | SND_FAIL |
M005 | 실패 | 문자 메시지 수신 거부 | SND_FAIL |
M006 | 실패 | 문자 메시지 발송 경로 설정 실패 | SND_FAIL |
M007 | 실패 | 국가별 제한 설정으로 인한 발송 실패 | SND_FAIL |
M100 | 성공 | 단말까지 전송 성공 | DONE |
M201 | 실패 | 잘못된 전화번호(결번) | DONE |
M202 | 실패 | 해당 전화번호의 이동통신사 가입자 없음 | DONE |
M203 | 실패 | 단말기 일시 정지상태 | DONE |
M204 | 실패 | 수신, 서비스 거부 | DONE |
M205 | 실패 | 이동통신사 단말기 전송 실패 | DONE |
M206 | 실패 | 이동통신사 필터링 | DONE |
M207 | 실패 | 발신번호 미등록 | DONE |
M208 | 실패 | 사용할 수 없는 첨부파일 | DONE |
M209 | 실패 | MMS 미지원 단말 | DONE |
M210 | 실패 | 착신번호 에러 또는 없는 국번 | DONE |
M299 | 실패 | 기타 에러 | DONE |
요청
curl -v -X POST "https://kims-api.kakao.com/api/v1/message/send/sms" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \-H "Content-Type: application/json" \-d '{"caller_number":"15773754","receivers": [{"receiver_number":"01000000000","content":"안녕하세요."}]}'
응답
// HTTP/1.1 200 OK// Content-Type: application/json{"request_id": 69386,"messages": [{"message_id": 69452,"type": "SMS","country_code": "82","caller_number": "15773754","receiver_number": "01000000000","content": "안녕하세요.","status_code": "READY","status_msg": "전송대기(업체로 메시지 전송 대기 중)"}]}
문자 메시지 발송 결과를 확인합니다. 발송 요청 ID(request_id)로 동보 발송된 문자 메시지 전체의 발송 결과를 확인할 수 있습니다. 문자 메시지 발송 결과는 발송 결과 알림으로 전달되지만, 별도 확인이 필요한 경우에 이 API를 사용합니다.
헤더에 서비스 앱 어드민 키를 담아 GET으로 요청합니다. 발송 요청 ID를 쿼리 파라미터로 전달해야 합니다.
요청 성공 시 응답은 요청 정보, 각 문자 메시지 정보 및 발송 결과를 포함합니다.
요청 실패 시 에러 코드로 원인을 확인합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}인증 방식, 서비스 앱 어드민 키로 인증 요청 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| request_id | String | 발송 요청 ID | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| request_id | String | 발송 요청 ID | O |
| request_date | String | 발송 요청 일시, 한국 표준시(KST) 시간대로 고정된 ISO8601 형식(예: 2024-06-13T15:25:47+09:00) | O |
| messages | Message[] | 문자 메시지 정보와 발송 결과 | O |
요청
curl -v -G GET "https://kims-api.kakao.com/api/v1/message" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \--data-urlencode "request_id=69422"
응답
// HTTP/1.1 200 OK// Content-Type: application/json{"request_id": 69422,"request_date": "2024-06-13T15:25:45+09:00","messages": [{"message_id": 69488,"type": "SMS","country_code": "1","caller_number": "15773754","receiver_number": "01000000000","content": "안녕하세요.","status_code": "DONE","status_msg": "처리완료(업체로 부터 결과 수신 완료)","result_code": "M100","result_msg": "성공(단말까지 전송 성공)","report_date": "2024-06-13T15:25:47+09:00"}]}
특정 문자 메시지 1건의 발송 결과를 확인합니다. 문자 메시지 ID(message_id)로 특정 문자 메시지 1건의 발송 결과를 확인할 수 있습니다. 문자 메시지 발송 결과는 발송 결과 알림으로 전달되지만, 별도 확인이 필요한 경우에 이 API를 사용합니다.
헤더에 서비스 앱 어드민 키를 담아 GET으로 요청합니다. 문자 메시지 ID를 경로 변수에 전달해야 합니다.
요청 성공 시 응답은 문자 메시지 정보 및 발송 결과를 포함합니다.
요청 실패 시 에러 코드로 원인을 확인합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}인증 방식, 서비스 앱 어드민 키로 인증 요청 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| MESSAGE_ID | Long | 문자 메시지 ID | O |
Message참고
요청
curl -v -G GET "https://kims-api.kakao.com/api/v1/message/${MESSAGE_ID}" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}"
응답
// HTTP/1.1 200 OK// Content-Type: application/json{"message_id": 69488,"type": "SMS","country_code": "1","caller_number": "15773754","receiver_number": "01000000000","content": "안녕하세요.","status_code": "DONE","status_msg": "처리완료(업체로 부터 결과 수신 완료)","result_code": "M100","result_msg": "성공(단말까지 전송 성공)","report_date": "2024-06-13T15:25:47+09:00"}
수신 거부 등록을 요청합니다.
헤더에 서비스 앱 어드민 키를 담아 POST로 요청합니다. 수신 거부할 전화번호를 쿼리 파라미터로 전달해야 합니다.
요청 성공 시 응답은 요청 정보, 각 문자 메시지 정보 및 발송 결과를 포함합니다.
요청 실패 시 에러 코드로 원인을 확인합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}인증 방식, 서비스 앱 어드민 키로 인증 요청 | O |
| Content-Type | 요청 데이터 타입, 아래 중 하나
| X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| request_number | String | 수신 거부로 등록할 전화 번호 하이픈( -) 없이 숫자만 입력 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| user_number | String | 수신 거부를 요청한 전화 번호 | O |
| is_withdrawn | Boolean | 수신거부 철회 여부 수신거부 등록 시 항상 false 반환 | O |
| created_at | String | 해당 번호가 최초로 수신거부 등록된 일자(레코드 생성일) | O |
| updated_at | String | 해당 번호가 마지막으로 수신거부 등록된 일자(레코드 수정일) | O |
요청
curl -v -X POST "https://kims-api.kakao.com/api/v1/message/refusal" \-H 'Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}' \-H 'Content-Type: application/x-www-form-urlencoded' \-d 'request_number=01012345678'
응답
// HTTP/1.1 200 OK// Content-Type: application/json{"user_number": "01012345678","is_withdrawn": false,"created_at": "2024-12-10 15:20:08","updated_at": "2024-12-10 15:20:08"}
수신 거부 처리된 전화 번호를 삭제합니다.
헤더에 서비스 앱 어드민 키를 담아 DELETE로 요청합니다. 요청할 전화 번호를 쿼리 파라미터로 전달해야 합니다.
요청 성공 시 응답은 바디가 없는 HTTP 204 상태 코드입니다.
요청 실패 시 에러 코드로 원인을 확인합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}인증 방식, 서비스 앱 어드민 키로 인증 요청 | O |
| Content-Type | 요청 데이터 타입, 아래 중 하나
| X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| request_number | String | 삭제할 전화 번호 하이픈( -) 없이 숫자만 입력 | O |
요청
curl -v -G -X DELETE "https://kims-api.kakao.com/api/v1/message/refusal" \-H 'Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}' \-H 'Content-Type: application/x-www-form-urlencoded' \-d 'request_number=01012345678'
응답
HTTP/1.1 204 No Content
사용자가 휴대전화 단말기에서 발송한(MO, Mobile Originated) SMS 메시지를 수신할 수 있는 번호 할당을 요청합니다.
헤더에 서비스 앱 어드민 키를 담아 POST로 요청합니다. 요청 성공 시 응답은 할당 요청 ID, 수신 번호 정보, 요청 상태를 포함합니다. 요청 실패 시 에러 코드로 원인을 확인합니다.
할당받은 수신 번호를 사용자에게 전달하고 메시지를 수신하는 방법은 수신 과정에서 확인할 수 있습니다.
MO 메시지는 세 가지의 수신 상태를 가집니다. 수신 번호 할당 요청 단계에서의 응답은 항상 WAITING 상태입니다. 사용자가 MO 메시지를 전송하면 MATCHED 또는 UNMATCHED 상태가 됩니다.
status 값 | MO 메시지 상태 | 필요 조치 |
|---|---|---|
WAITING | 서비스에서 수신 번호 할당 요청을 완료했으나, 사용자가 MO 메시지를 발송하지 않은 상태 | 사용자에게 MO 메시지 발송을 요청하지 않은 경우 요청 필요, 수신 과정 참고 |
MATCHED | 서비스에서 수신 번호 할당 요청을 완료하고 사용자가 해당 번호로 MO 메시지 발송을 완료한 상태 | 문자 메시지 수신 웹훅의 content 값으로 사용자가 발송한 MO 메시지 내용 확인 |
UNMATCHED | 서비스의 수신 번호 할당 요청 없이 사용자가 문자 메시지 전송을 완료한 상태, 서비스의 요청과 사용자의 응답 불일치 | 수신 과정을 참고해 수신 번호 할당 요청 및 MO 메시지 발송 요청 필요 |
- 요청 시,
sender또는sender_country_code중 최소 하나는 필수로 포함해야 합니다. sender를 포함할 경우, 매칭 키는sender와content조합으로 구성됩니다. 이때sender가 동일한content를 전송한 경우에만MATCHED로 응답합니다.sender_country_code만 포함한 경우,content기준으로만 매칭하여MATCHED또는UNMATCHED로 응답합니다. 이 경우, 요청 시 전달한sender_country_code와 실제 발신자의sender_country_code가 다를 수 있으며, 최종 값은 실제 메시지 발신자 기준 국가코드로 전달됩니다.- 동일
content를 제3자가 임의로 전송하여 인증을 우회할 수 있는 보안 위험이 있으므로,sender와content조합으로 사용하는 것을 권장합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}인증 방식, 서비스 앱 어드민 키로 인증 요청 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| sender | String | MO 메시지 발송을 요청할 대상(사용자)의 국가코드를 포함한 전화번호(E.164 규격 형식) 플러스( +) 또는 하이픈(-) 없이 숫자만 입력지원 가능 국가가 아닌 경우 실패 처리(참고: 과금 단가) 참고: 할당 단계 참고사항 | O* |
| sender_country_code | String | MO 메시지 발송을 요청할 국가의 국가 번호 더하기( +) 기호 없이 숫자만 입력지원 가능 국가가 아닌 경우 실패 처리(참고: 과금 단가) 참고: 할당 단계 참고사항 | O* |
| content | String | 사용자에게 전달할 MO 메시지 발송 요청문 제약 조건: 최대 160자 허용, 숫자와 영문자만 허용, 특수문자와 국문자 불가 | O |
sender 또는 sender_country_code 중 최소 하나 필수
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| id | Long | 수신 번호 할당 요청 ID | O |
| sender | String | MO 메시지 발송을 요청할 대상(사용자)의 국가코드를 포함한 전화번호, 요청 본문에 sender_country_code를 포함한 경우 null로 응답 | X |
| sender_country_code | String | MO 메시지 발송을 요청할 대상(사용자)의 국가코드 | O |
| receiver | String | 할당된 MO 메시지 수신 번호(국가코드 포함), 미할당 상태인 경우 null로 응답 사전에 KIMS 담당자에게 발급받은 MO 번호 중 하나가 할당됨 E.164 규격 형식 또는 SMS 단축 코드(Short Code) 등 다양한 번호 유형으로 응답할 수 있음 | X |
| receiver_country_code | String | 할당된 MO 메시지 수신 번호의 국가 코드, 미할당 상태인 경우 null로 응답 | X |
| content | String | 사용자에게 전달할 MO 메시지 발송 요청문 | O |
| status | String | MO 메시지 수신 상태, 문자 메시지 수신 번호 할당 요청 시 WAITING으로 고정 | O |
| request_date | String | 수신 번호 할당 요청 일시, 한국 표준시(KST) 시간대로 고정된 ISO8601 형식(예: 2025-10-13T15:25:47+09:00) | O |
| updated_date | String | MO 메시지 수신 상태 변경 일시, 문자 메시지 수신 번호 할당 요청 시 WAITING으로 고정 | O |
요청
curl -v -X POST "https://kims-api.kakao.com/api/v1/mo/request" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \-d "sender=821000000000" \-d "content=${CONTENT}"
응답
{"id": "8","sender": "821000000000","sender_country_code": "82","receiver": "440000000000","receiver_country_code": "44","content": "${MO_REQUEST_CONTENT}","status": "UNMATCHED","requested_date": "WAITING","updated_date": "WAITING"}
문자 메시지 수신 번호 할당 API로 할당받은 번호로, 사용자가 휴대전화 단말기에서 발송한(MO, Mobile Originated) SMS 메시지의 수신 상태를 조회합니다.
헤더에 서비스 앱 어드민 키를 담아 GET로 요청합니다. 문자 메시지 수신 번호 할당 API의 응답에 포함된 id를 경로 변수로 포함해야 합니다.
요청 성공 시 응답은 할당 요청 ID, 수신 번호 정보, 수신 상태를 포함합니다. 요청 실패 시 에러 코드로 원인을 확인합니다.
할당받은 수신 번호를 사용자에게 전달하고 메시지를 수신하는 방법은 수신 과정에서 확인할 수 있습니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}인증 방식, 서비스 앱 어드민 키로 인증 요청 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| ID | Long | 문자 메시지 수신 번호 할당 API의 응답에 포함된 수신 번호 할당 요청 ID | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| id | Long | 수신 번호 할당 요청 ID | O |
| sender | String | MO 메시지 발송을 요청할 대상(사용자)의 국가코드를 포함한 전화번호 | O |
| sender_country_code | String | MO 메시지 발송을 요청할 대상(사용자)의 국가코드 메시지가 발신 완료된 경우, 실제 발신자의 국가코드로 반환될 수 있음 (참고: 할당 단계 참고사항) | O |
| receiver | String | 할당된 MO 메시지 수신 번호(국가코드 포함), 미할당 상태인 경우 null로 응답 | X |
| receiver_country_code | String | 할당된 MO 메시지 수신 번호의 국가 코드, 미할당 상태인 경우 null로 응답 | X |
| content | String | 사용자에게 전달할 MO 메시지 발송 요청문 | O |
| status | String | MO 메시지 수신 상태 | O |
| request_date | String | 문자 메시지 수신 번호 할당 API 요청 일시, 한국 표준시(KST) 시간대로 고정된 ISO8601 형식(예: 2025-10-13T15:25:47+09:00) | O |
| updated_date | String | MO 메시지 수신 상태 변경 일시, 한국 표준시(KST) 시간대로 고정된 ISO8601 형식(예: 2025-10-13T15:25:47+09:00) | O |
요청
curl -v -X POST "https://kims-api.kakao.com/api/v1/mo/${ID}" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}"
응답
{"id": "8","sender": "821000000000","sender_country_code": "82","receiver": "440000000000","receiver_country_code": "44","content": "${MO_REQUEST_CONTENT}","status": "UNMATCHED","request_date": "2025-10-13T15:25:47+09:00","updated_date": "2025-10-13T15:25:47+09:00"}