페이지 이동경로
- 문서>
- 카카오모먼트>
- 개인화 메시지 관리
카카오모먼트
개인화 메시지 관리
이 문서는 개인화 메시지 관리 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 |
PersonalMessageSendRequest
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| 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[] |
다건 발송건 각각의 결과 리스트 |
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[] |
업로드 실패 이미지와 사유 |
ImageFile
| 이름 | 타입 | 설명 |
|---|---|---|
| downloadUrl | String |
이미지 주소 |
| originalFileName | String |
이미지 파일명 |
InvalidFile
| 이름 | 타입 | 설명 |
|---|---|---|
| fileName | String |
업로드 실패 파일명 |
| invalidReasons | InvalidReason[] |
사유 |
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[] |
등록 실패 사유 |
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 채널에 권한이 없습니다."
}
]
}