이 문서는 개인화 메시지 관리 API 사용 방법을 안내합니다.
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://apis.moment.kakao.com/openapi/v4/messages/creatives/${ID}/sendTestPersonalMessage |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
필요: 사용 권한 신청 | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
개인화 메시지 X 도달 캠페인 하위의 소재의 테스트 발송을 요청합니다. 발송 시에 홍보문구 영역에 [테스트 발송]이 추가되어 발송됩니다.
비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 POST
로 요청합니다. API 요청 성공 시 응답 본문은 비어있습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이 API는 사용자 계정, 광고계정마다 1분에 한 번씩 요청 가능하도록 제한되어 있습니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN} 인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
Name | Type | Description | Required |
---|---|---|---|
ID | Integer |
소재 번호 | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
phoneNumber | String |
발송 대상 전화번호 | O |
variables | JSON |
템플릿 사용 변수의 키-값 쌍을 가지는 객체 | O |
curl -X POST "https://apis.moment.kakao.com/openapi/v4/messages/creatives/1/sendTestPersonalMessage" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: 1" \
-H "Content-Type: application/json" \
-d '{
"phoneNumber": "010-1234-1234",
"variables": {
"image_url1": "https://t1.daumcdn.net/b2/personalMessage/1/testImage.jpg",
"user_name1": "테스트유저"
}
}'
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://apis.moment.kakao.com/openapi/v4/messages/creatives/${ID}/sendPersonalMessage |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
필요: 사용 권한 신청 | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
개인화 메시지 X 도달 캠페인 하위의 소재의 발송을 요청합니다. 한 번에 한 명의 사용자에게만 발송 가능합니다.
비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 POST
로 요청합니다. 단건 발송은 동기로 이루어집니다.
요청 성공 시 응답 본문의 JSON 객체는 발송 결과에 관한 정보들을 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN} 인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
Name | Type | Description | Required |
---|---|---|---|
ID | Integer |
소재 번호 | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
messageSerialNumber | String |
발송 메시지를 구분할 수 있는 고유 ID 패턴 규칙은 아래를 따름 yyyyMMdd-${creativeId}-${uniqueId_for_message} 총 길이 39자를 넘지 않아야 함 단건 발송에서는 messageSerialNumber 가 자동으로 발송 요청 고유 ID(requestId)로 세팅됨 |
O |
receiverType | String |
발송 유형, 다음 중 하나APP_USER_ID : 개인화 메시지 소재 템플릿의 profileId 에 연결된 앱의 회원번호PHONE_NUMBER : 전화번호 |
O |
receiverKey | String |
발송 대상 식별자 유저식별자 혹은 전화번호 |
O |
variables | JSON |
템플릿 사용 변수의 키-값 쌍을 가지는 객체 | O |
이름 | 타입 | 설명 |
---|---|---|
requestId | String |
발송 요청 고유 ID 발송 상태 조회 시 사용 |
messageSerialNumber | String |
발송 요청 시 전달했던 발송 메시지 고유 ID |
status | String |
발송 결과, 다음 중 하나SUCCEEDED (발송 성공)FAILED (발송 실패) |
sendAt | String |
발송일시yyyy-MM-dd HH:mm:ss 형식 |
curl -X POST "https://apis.moment.kakao.com/openapi/v4/messages/creatives/1/sendPersonalMessage" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: 1" \
-H "Content-Type: application/json" \
-d '{
"messageSerialNumber": "20230731-1-send1",
"receiverType": "PHONE_NUMBER",
"receiverKey": "010-1234-1234",
"variables": {
"image_url1": "https://t1.daumcdn.net/b2/personalMessage/1/testImage.jpg",
"user_name1": "테스트유저"
}
}'
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"requestId": "20230731-1-001",
"messageSerialNumber": "20230731-1-send1",
"status": "SUCCEEDED",
"sendAt": "2023-07-31 16:00:00"
}
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://apis.moment.kakao.com/openapi/v4/messages/creatives/${ID}/sendPersonalMessages |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
필요: 사용 권한 신청 | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
개인화 메시지 X 도달 캠페인 하위의 소재의 발송을 요청합니다. 최소 2건에서 최대 100건을 한 번에 발송 요청할 수 있습니다.
비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 POST
로 요청합니다. 유효하지 않은 값이 요청되는 경우 즉시 응답되고, 유효성이 체크된 다건 발송은 비동기로 이루어집니다.
요청 성공 시 응답 본문의 JSON 객체는 발송 상태를 확인할 수 있는 requestId를 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN} 인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
Name | Type | Description | Required |
---|---|---|---|
ID | Integer |
소재 번호 | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
requestId | String |
발송 요청을 구분할 수 있는 고유 ID 각 발송 요청 호출 시 생성하여 전달하여야 하며 패턴 규칙은 아래를 따름 yyyyMMdd-${creativeId}-${uniqueId_for_request} 총 길이 39자를 넘지 않도록 하여야 함 |
O |
receivers | PersonalMessageSendRequest[] |
발송 메시지 각각에 대한 정보 | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
messageSerialNumber | String |
발송 메시지를 구분할 수 있는 고유 ID 패턴 규칙은 아래를 따름 yyyyMMdd-${creativeId}-${uniqueId_for_message} 총 길이 39자를 넘지 않아야 함 단건 발송에서는 messageSerialNumber 가 자동으로 발송 요청 고유 ID(requestId)로 세팅됨 |
O |
receiverType | String |
발송 유형, 다음 중 하나APP_USER_ID : 개인화 메시지 소재 템플릿의 profileId 에 연결된 앱의 회원번호PHONE_NUMBER : 전화번호 |
O |
receiverKey | String |
발송 대상 식별자 유저식별자 혹은 전화번호 |
O |
variables | JSON |
템플릿 사용 변수의 키-값 쌍을 가지는 객체 | O |
이름 | 타입 | 설명 |
---|---|---|
requestId | String |
발송 요청 고유 ID 발송 상태 조회 시 사용 |
curl -X POST "https://apis.moment.kakao.com /openapi/v4/messages/creatives/1/sendPersonalMessages " \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: 1" \
-H "Content-Type: application/json" \
-d '{
"requestId": "20230731-1-request1",
"receivers": [
{
"messageSerialNumber": "20230731-1-send1",
"receiverType": "PHONE_NUMBER",
"receiverKey": "010-1234-1234",
"variables": {
"image_url1": "https://t1.daumcdn.net/b2/personalMessage/1/testImage1.jpg",
"user_name1": "테스트유저1"
}
},
{
"messageSerialNumber": "20230731-1-send2",
"receiverType": "PHONE_NUMBER",
"receiverKey": "010-4321-4321",
"variables": {
"image_url1": "https://t1.daumcdn.net/b2/personalMessage/1/testImage2.jpg",
"user_name1": "테스트유저2"
}
}
]
}'
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"requestId": "20230731-1-request1"
}
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://apis.moment.kakao.com/openapi/v4/messages/creatives/${ID}/statuses/${REQUEST_ID} |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
필요: 사용 권한 신청 | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
개인화 메시지 발송 요청에 대한 결과를 조회합니다. 발송 요청으로부터 90일 이내에만 결과만 조회 가능합니다.
비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 GET
으로 요청합니다.
요청 성공 시 응답은 발송 완료 여부, 각 메시지의 발송 결과를 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN} 인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
Name | Type | Description | Required |
---|---|---|---|
ID | Integer |
소재 번호 | O |
REQUEST_ID | String |
요청 고유 ID | O |
이름 | 타입 | 설명 |
---|---|---|
completed | Boolean |
다건 발송 시도 완료 여부 모든 발송 시도를 완료하지 않았을 때는 false 이고, results 는 빈 배열 반환 |
results | PersonalMessageResult[] |
다건 발송건 각각의 결과 리스트 |
이름 | 타입 | 설명 |
---|---|---|
messageSerialNumber | String |
발송 메시지를 구분할 수 있는 고유 ID |
status | String |
발송 결과, 다음 중 하나SUCCEEDED (발송 성공)FAILED (발송 실패) |
statusReason | String |
발송 결과 상세 사유 |
sendAt | String |
발송일시, yyyy-MM-dd HH:mm:ss 형식 |
curl -X GET "https://apis.moment.kakao.com/openapi/v4/messages/creatives/${ID}/statuses/${REQUEST_ID}" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"completed": true,
"results": [
{
"status": "SUCCEEDED",
"sendAt": "2023-07-31 16:00:00"
}
]
}
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://apis.moment.kakao.com/openapi/v4/messages/personal/images/upload |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
필요: 사용 권한 신청 | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
개인화 메시지 X 도달 캠페인 하위 소재에 사용할 홍보 이미지를 업로드합니다. 최소 1건에서 최대 100건을 한번에 요청할 수 있습니다.
카카오는 메시지 정책에 맞는 이미지 정책과 사이즈 여부를 확인 후 내부의 안정적인 저장소로 저장합니다.
비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 POST
로 요청합니다.
요청 성공 시 개인화 메시지 발송 시 사용할 수 있는 이미지 URL을 받을 수 있습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
메시지 내용에 포함할 이미지만 업로드해야 합니다. 이외 목적으로 이미지 업로드 시 광고계정 운영 제재 등 불이익을 받을 수 있습니다. 또한, 가능한 메시지 발송 시점에 맞춰 이미지를 업로드할 것을 권장합니다. 응답 이미지 URL은 영구적으로 사용할 수 없으며, 등록한 이미지는 카카오 시스템 사정에 의해 통보없이 삭제될 수 있습니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN} 인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
files | Multipart file[] |
업로드할 이미지 파일 파일 형식: JPG, JPEG, PNG 권장 사이즈: 800x400(2:1 비율), 800x800(1:1 비율), 800x600(4:3 비율) 용량: 10MB 이하 |
O |
이름 | 타입 | 설명 |
---|---|---|
successFiles | ImageFile[] |
업로드 성공 이미지 정보 |
invalidFiles | InvalidFile[] |
업로드 실패 이미지와 사유 |
이름 | 타입 | 설명 |
---|---|---|
downloadUrl | String |
이미지 주소 |
originalFileName | String |
이미지 파일명 |
이름 | 타입 | 설명 |
---|---|---|
fileName | String |
업로드 실패 파일명 |
invalidReasons | InvalidReason[] |
사유 |
이름 | 타입 | 설명 |
---|---|---|
reason | String |
사유 |
description | String |
상세 설명 |
curl -X POST "https://apis.moment.kakao.com/openapi/v4/messages/personal/images/upload" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: {adAccountId}"
-F "files[0]=@image.jpg"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"successFiles": [
{
"originalFileName": "string",
"downloadUrl": "string"
}
],
"invalidFiles": [
{
"fileName": "string",
"invalidReasons": [
{
"reason": "string",
"description": "string"
}
]
}
]
}
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://apis.moment.kakao.com/openapi/v4/messages/personal/videos/register |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
필요: 사용 권한 신청 | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
개인화 메시지 X 도달 캠페인 하위 소재에 사용할 홍보 동영상으로 활용하고자 하는 카카오TV URL 등록하여 사전에 유효성 체크를 진행합니다. 최소 1건에서 최대 100건을 한번에 요청할 수 있습니다.
카카오 TV 채널의 오너 계정으로 등록 요청해야 합니다.
이 API로 등록되지 않은 카카오TV URL은 발송 시 개인화 메시지 소재로 활용이 불가합니다.
비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 POST
로 요청합니다.
요청 성공 시 응답은 동영상 등록 여부를 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN} 인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
kakaoTVUrls | String[] |
등록할 카카오TV 동영상 주소 목록 | O |
이름 | 타입 | 설명 |
---|---|---|
successVideoUrls | String[] |
등록 성공 카카오TV 동영상 주소 목록 |
invalidKakaoTVUrls | InvalidKakaoTV[] |
등록 실패 사유 |
이름 | 타입 | 설명 |
---|---|---|
kakaoTVUrl | String |
등록 실패한 카카오TV 동영상 주소 |
reason | String |
사유 |
curl -X POST "https://apis.moment.kakao.com/openapi/v4/messages/personal/videos/register" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
-d '{"kakaoTVUrls": ["http://tv.kakao.com/v/111","http://tv.kakao.com/1/222", "https://tv.kakao.com/v/333"]
}'
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"successVideoUrls": [
"https://tv.kakao.com/v/111"
],
"invalidKakaoTVUrls": [
{
"kakaoTVUrl": "https://tv.kakao.com/l/222",
"reason": "해당 영상은 메시지 홍보 동영상으로 사용할 수 없습니다."
},
{
"kakaoTVUrl": "https://tv.kakao.com/v/333",
"reason": "해당 카카오TV 채널에 권한이 없습니다."
}
]
}