페이지 이동경로
  • 문서>
  • 카카오모먼트>
  • 개인화 메시지 관리

카카오모먼트

개인화 메시지 관리

이 문서는 개인화 메시지 관리 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 채널에 권한이 없습니다."
    }
  ]
}

더 보기