카카오모먼트

개인화 메시지 관리

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

개인화 메시지 테스트 발송

기본 정보

메서드	URL	인증 방식
`POST`	`https://apis.moment.kakao.com/openapi/v4/messages/creatives/${ID}/sendTestPersonalMessage`	비즈니스 토큰

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	비즈 앱 전환 비즈니스 인증 리다이렉트 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`	비즈니스 토큰

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	비즈 앱 전환 비즈니스 인증 리다이렉트 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`	비즈니스 토큰

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	비즈 앱 전환 비즈니스 인증 리다이렉트 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}`	비즈니스 토큰

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	비즈 앱 전환 비즈니스 인증 리다이렉트 URI 비즈니스 동의항목	필요	필요

개인화 메시지 발송 요청에 대한 결과를 조회합니다.

발송 요청으로부터 7일 이내의 결과만 조회 가능합니다.

비즈니스 토큰과 광고계정 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`	비즈니스 토큰

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	비즈 앱 전환 비즈니스 인증 리다이렉트 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`	비즈니스 토큰

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	비즈 앱 전환 비즈니스 인증 리다이렉트 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 채널에 권한이 없습니다."
    }
  ]
}

사이드 메뉴

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

카카오맵

내비게이션

광고

검색

더 보기

개인화 메시지 관리

개인화 메시지 테스트 발송

기본 정보

요청

헤더

경로 변수

본문

예제

요청

응답

개인화 메시지 단건 발송 요청

기본 정보

요청

헤더

경로 변수

본문

응답

본문

예제

요청

응답

개인화 메시지 다건 발송 요청

기본 정보

요청

헤더

경로 변수

본문

PersonalMessageSendRequest

응답

본문

예제

요청

응답

개인화 메시지 발송 상태 조회

기본 정보

요청

헤더

경로 변수

응답

본문

PersonalMessageResult

예제

요청

응답

개인화 메시지 이미지 업로드

기본 정보

요청

헤더

본문

응답

본문

ImageFile

InvalidFile

InvalidReason

예제

요청

응답

개인화 메시지 비디오 등록

기본 정보

요청

헤더

본문

응답

본문

InvalidKakaoTV

예제

요청

응답

더 보기

도움이 되었나요?