개인화 메시지 관리

이 문서는 개인화 메시지 관리 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: 개인화 메시지 소재 템플릿의 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 ${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: 개인화 메시지 소재 템플릿의 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 ${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 채널에 권한이 없습니다."
    }
  ]
}

더 보기

카카오모먼트 API 레퍼런스