카카오모먼트

개인화 메시지 관리

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

개인화 메시지 테스트 발송

기본 정보

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

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

개인화 메시지 X 도달 캠페인 하위 소재를 테스트 발송합니다.

발송 시에 홍보문구 영역에 [테스트 발송]이 추가되어 발송됩니다.

요청 수 제한

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

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	광고계정 ID `adAccountId: ${AD_ACCOUNT_ID}`	O

경로 변수

이름	타입	설명	필수
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 도달 캠페인 하위 소재를 한 명의 사용자에게 발송합니다.

사용 조건

한 번에 한 명의 사용자에게만 발송 가능
단건 발송은 동기로 처리

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	광고계정 ID `adAccountId: ${AD_ACCOUNT_ID}`	O

경로 변수

이름	타입	설명	필수
ID	`Integer`	소재 번호	O

본문

이름	타입	설명	필수
messageSerialNumber	`String`	발송 메시지를 구분하는 고유 ID(최대: 39자) 형식: `yyyyMMdd-${creativeId}-${uniqueId_for_message}` 참고: 단건 발송에서는 `messageSerialNumber`가 발송 요청 고유 ID(`requestId`)로 자동 설정됨	O
receiverType	`Enum`	발송 유형 `APP_USER_ID`: 개인화 메시지 소재 템플릿의 `profileId`에 연결된 앱의 회원번호 `PHONE_NUMBER`: 전화번호	O
receiverKey	`String`	발송 대상 식별자 유저식별자 혹은 전화번호	O
variables	`JSON`	템플릿 사용 변수의 키-값 쌍을 가지는 객체	O

응답

본문

이름	타입	설명
requestId	`String`	발송 요청 고유 ID 발송 상태 조회 시 사용
messageSerialNumber	`String`	발송 요청 시 전달했던 발송 메시지 고유 ID
status	`Enum`	발송 결과 `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건까지 발송 요청 가능
유효하지 않은 값이 포함된 경우 즉시 응답
유효성 검사를 통과한 다건 발송은 비동기로 처리

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	광고계정 ID `adAccountId: ${AD_ACCOUNT_ID}`	O

경로 변수

이름	타입	설명	필수
ID	`Integer`	소재 번호	O

본문

이름	타입	설명	필수
requestId	`String`	발송 요청을 구분하는 고유 ID(최대: 39자), 발송 요청마다 새로 생성해 전달 형식: `yyyyMMdd-${creativeId}-${uniqueId_for_request}`	O
receivers	`PersonalMessageSendRequest[]`	발송 메시지 각각에 대한 정보	O

PersonalMessageSendRequest

이름	타입	설명	필수
messageSerialNumber	`String`	발송 메시지를 구분하는 고유 ID(최대: 39자) 형식: `yyyyMMdd-${creativeId}-${uniqueId_for_message}` 참고: 단건 발송에서는 `messageSerialNumber`가 발송 요청 고유 ID(`requestId`)로 자동 설정됨	O
receiverType	`Enum`	발송 유형 `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일 이내의 결과만 조회 가능합니다.

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	광고계정 ID `adAccountId: ${AD_ACCOUNT_ID}`	O

경로 변수

이름	타입	설명	필수
ID	`Integer`	소재 번호	O
REQUEST_ID	`String`	요청 고유 ID	O

응답

본문

이름	타입	설명
completed	`Boolean`	다건 발송 시도 완료 여부 모든 발송 시도를 완료하지 않았을 때는 `false`이고, `results`는 빈 배열 반환
results	`PersonalMessageResult[]`	다건 발송건 각각의 결과 리스트

PersonalMessageResult

이름	타입	설명
messageSerialNumber	`String`	발송 메시지를 구분할 수 있는 고유 ID
status	`Enum`	발송 결과 `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건을 한번에 요청할 수 있습니다.

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

이미지 업로드 주의 사항

메시지 내용에 포함할 이미지만 업로드해야 합니다. 이외 목적으로 이미지 업로드 시 광고계정 운영 제재 등 불이익을 받을 수 있습니다.
가능한 메시지 발송 시점에 맞춰 이미지를 업로드할 것을 권장합니다.
응답 이미지 URL은 영구적으로 사용할 수 없으며, 등록한 이미지는 카카오 시스템 사정에 의해 통보없이 삭제될 수 있습니다.

요청

헤더

이름	설명	필수
Authorization	인증 방식, 비즈니스 토큰으로 인증 요청 `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	광고계정 ID `adAccountId: ${AD_ACCOUNT_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: ${AD_ACCOUNT_ID}" \
    -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"
        }
      ]
    }
  ]
}

사이드 메뉴

문서 홈

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

광고

지도

내비게이션

검색

더 보기

개인화 메시지 관리

개인화 메시지 테스트 발송

기본 정보

요청 수 제한

요청

헤더

경로 변수

본문

예제

요청

응답

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

기본 정보

사용 조건

요청

헤더

경로 변수

본문

응답

본문

예제

요청

응답

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

기본 정보

사용 조건

요청

헤더

경로 변수

본문

PersonalMessageSendRequest

응답

본문

예제

요청

응답

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

기본 정보

요청

헤더

경로 변수

응답

본문

PersonalMessageResult

예제

요청

응답

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

기본 정보

이미지 업로드 조건

요청

헤더

본문

응답

본문

ImageFile

InvalidFile

InvalidReason

예제

요청

응답

더 보기

도움이 되었나요?

개인화 메시지 관리

개인화 메시지 테스트 발송

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

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

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

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