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

카카오모먼트

개인화 메시지 관리

이 문서는 개인화 메시지 관리 API 사용 방법을 안내합니다.

개인화 메시지 테스트 발송하기

기본 정보
메서드 URL 인증 방식
POST https://apis.moment.kakao.com/openapi/v4/messages/creatives/${ID}/sendTestPersonalMessage 액세스 토큰
권한 사전 설정 카카오 로그인 사용자 동의
필요 플랫폼 등록
카카오 로그인 활성화
비즈 앱
필요 -

개인화 메시지 X 도달 캠페인 하위의 소재의 테스트 발송을 요청합니다. 발송 시에 홍보문구 영역에 [테스트 발송]이 추가되어 발송됩니다.

액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 POST로 요청합니다. API 요청 성공 시 응답 본문은 비어있습니다. 실패 시 에러 코드상세 에러 코드로 사유를 확인합니다.

이 API는 사용자 계정, 광고계정마다 1분에 한 번씩 요청 가능하도록 제한되어 있습니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${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 ${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 액세스 토큰
권한 사전 설정 카카오 로그인 사용자 동의
필요 플랫폼 등록
카카오 로그인 활성화
비즈 앱
필요 -

개인화 메시지 X 도달 캠페인 하위의 소재의 발송을 요청합니다. 한 번에 한 명의 사용자에게만 발송 가능합니다.

액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 POST로 요청합니다. 단건 발송은 동기로 이루어집니다.

요청 성공 시 응답 본문의 JSON 객체는 발송 결과에 관한 정보들을 포함합니다. 실패 시 에러 코드상세 에러 코드로 사유를 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${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(회원번호)
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 ${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 액세스 토큰
권한 사전 설정 카카오 로그인 사용자 동의
필요 플랫폼 등록
카카오 로그인 활성화
비즈 앱
필요 -

개인화 메시지 X 도달 캠페인 하위의 소재의 발송을 요청합니다. 최소 2건에서 최대 100건을 한 번에 발송 요청할 수 있습니다.

액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 POST로 요청합니다. 유효하지 않은 값이 요청되는 경우 즉시 응답되고, 유효성이 체크된 다건 발송은 비동기로 이루어집니다.

요청 성공 시 응답 본문의 JSON 객체는 발송 상태를 확인할 수 있는 requestId를 포함합니다. 실패 시 에러 코드상세 에러 코드로 사유를 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${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(회원번호)
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 ${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} 액세스 토큰
권한 사전 설정 카카오 로그인 사용자 동의
필요 플랫폼 등록
카카오 로그인 활성화
비즈 앱
필요 -

개인화 메시지 발송 요청에 대한 결과를 조회합니다. 발송 요청으로부터 90일 이내에만 결과만 조회 가능합니다.

액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청합니다.

요청 성공 시 응답은 발송 완료 여부, 각 메시지의 발송 결과를 포함합니다. 실패 시 에러 코드상세 에러 코드로 사유를 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${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 ${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 액세스 토큰
권한 사전 설정 카카오 로그인 사용자 동의
필요 플랫폼 등록
카카오 로그인 활성화
비즈 앱
필요 -

개인화 메시지 X 도달 캠페인 하위 소재에 사용할 홍보 이미지를 업로드합니다. 최소 1건에서 최대 100건을 한번에 요청할 수 있습니다.

카카오는 메시지 정책에 맞는 이미지 정책과 사이즈 여부를 확인 후 내부의 안정적인 저장소로 저장합니다.

액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 POST로 요청합니다.

요청 성공 시 개인화 메시지 발송 시 사용할 수 있는 이미지 URL을 받을 수 있습니다. 실패 시 에러 코드상세 에러 코드로 사유를 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${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 ${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 액세스 토큰
권한 사전 설정 카카오 로그인 사용자 동의
필요 플랫폼 등록
카카오 로그인 활성화
비즈 앱
필요 -

개인화 메시지 X 도달 캠페인 하위 소재에 사용할 홍보 동영상으로 활용하고자 하는 카카오TV URL 등록하여 사전에 유효성 체크를 진행합니다. 최소 1건에서 최대 100건을 한번에 요청할 수 있습니다.

카카오 TV 채널의 오너 계정으로 등록 요청해야 합니다.

이 API로 등록되지 않은 카카오TV URL은 발송 시 개인화 메시지 소재로 활용이 불가합니다.

액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 POST로 요청합니다.

요청 성공 시 응답은 동영상 등록 여부를 포함합니다. 실패 시 에러 코드상세 에러 코드로 사유를 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${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 ${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 채널에 권한이 없습니다."
    }
  ]
}

더 보기