페이지 이동경로
  • Docs>
  • Kakao Moment>
  • Personalized message management

Kakao Moment

Personalized message management

This document describes how to use the Personalized message management APIs.

Test sending personalized message

Basic information
Method URL Authorization
POST https://apis.moment.kakao.com/openapi/v4/messages/creatives/${ID}/sendTestPersonalMessage Business token
Permission Prerequisite Business Authentication Business consent items
Required:
Request permission		 Switch to a Biz app
Set Business redirect URI
Business consent items		 Required Required

This API enables you to send a test message of the Personal message X Reach campaign. The message sent by this API includes a text [테스트 발송].

Send a POST request with the Business token and ad account ID in the header. If the request is successful, the response has an empty body. If failed, refer to Error code to figure out its failure cause.

This API limits the number of calls you can make to every minute per user account and ad account.

Request

Header
Name Description Required
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.		 O
Path variable
Name Type Description Required
ID Integer Creative ID O
Body
Name Type Description Required
phoneNumber String Target's phone number. O
variables JSON A JSON object including key-value pairs for variables in the message template. O

Sample

Request
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": "Test user"
    }
 }'
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

Send a personalized message

Basic information
Method URL Authorization
POST https://apis.moment.kakao.com/openapi/v4/messages/creatives/${ID}/sendPersonalMessage Business token
Permission Prerequisite Business Authentication Business consent items
Required:
Request permission		 Switch to a Biz app
Set Business redirect URI
Business consent items		 Required Required

This API enables you to send a message of the Personal message X Reach campaign. You can send only one message at once with this API.

Send a POST request with the Business token and the ad account ID in the header. The delivery is made synchronously.

If the request is successful, the response includes information of the result. If failed, refer to Error code to figure out its failure cause.

Request

Header
Name Description Required
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.		 O
Path variable
Name Type Description Required
ID Integer Creative ID O
Body
Name Type Description Required
messageSerialNumber String A unique ID that identifies each sent message.
The length must be under 39 characters, and the pattern is below.
yyyyMMdd-${creativeId}-${uniqueId_for_message}
For the single delivery, messageSerialNumber is automatically set to the unique request ID (requestId).		 O
receiverType String Receiver ID type, one of:
APP_USER_ID: Service user ID of the app connected to Personalized message creative template profileId
PHONE_NUMBER: Phone number		 O
receiverKey String Receiver ID
A Service user ID or a phone number.		 O
variables JSON A JSON object including key-value pairs for variables in the message template. O

Response

Body
Name Type Description
requestId String A unique request ID
Used to retrieve the sending status.
messageSerialNumber String A unique ID that identifies each sent message.
status String Sending result, one of:
SUCCEEDED
FAILED
sendAt String Date the message was sent, in yyyy-MM-dd HH:mm:ss format.

Sample

Request
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": "테스트유저"
    }
 }'
Response
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"
}

Send multiple personalized message

Basic information
Method URL Authorization
POST https://apis.moment.kakao.com/openapi/v4/messages/creatives/${ID}/sendPersonalMessages Business token
Permission Prerequisite Business Authentication Business consent items
Required:
Request permission		 Switch to a Biz app
Set Business redirect URI
Business consent items		 Required Required

This API enables you to send a message of the Personal message X Reach campaign. With this API, you can send a minimum of 2 and 100 messages at once.

Send a POST request with the Business token and ad account ID in the header. If the request includes invalid values, the response will be returned immediately. Otherwise, messages will be sent asynchronously.

If the request is successful, the response includes a JSON object including the sending status. If failed, refer to Error code to figure out its failure cause.

Request

Header
Name Description Required
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.		 O
Path variable
Name Type Description Required
ID Integer Creative ID O
Body
Name Type Description Required
requestId String A unique request ID
The length must be under 39 characters, and the pattern is below.
yyyyMMdd-${creativeId}-${uniqueId_for_message}		 O
receivers PersonalMessageSendRequest[] Information for each message O
PersonalMessageSendRequest
Name Type Description Required
messageSerialNumber String A unique ID that identifies each sent message.
The length must be under 39 characters, and the pattern is below.
yyyyMMdd-${creativeId}-${uniqueId_for_message}
For the single delivery, messageSerialNumber is automatically set to the unique request ID (requestId).		 O
receiverType String Receiver ID type, one of:
APP_USER_ID: Service user ID of the app connected to Personalized message creative template profileId
PHONE_NUMBER: Phone number		 O
receiverKey String Receiver ID
A Service user ID or a phone number.		 O
variables JSON A JSON object including key-value pairs for variables in the message template. O

Response

Body
Name Type Description
requestId String A unique request ID
Used to retrieve the sending status.

Sample

Request
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": "Test user 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": "Test user 2"
            }
        }
    ]
 }'
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
 
{
    "requestId": "20230731-1-request1"
}

Retrieve sending status

Basic information
Method URL Authorization
GET https://apis.moment.kakao.com/openapi/v4/messages/creatives/${ID}/statuses/${REQUEST_ID} Business token
Permission Prerequisite Business Authentication Business consent items
Required:
Request permission		 Switch to a Biz app
Set Business redirect URI
Business consent items		 Required Required

This API enables you to retrieve sending status. You can retrieve sending status in 90 days from the request.

Send a GET request with the Business token and ad account ID in the header.

If the request is successful, the response includes whether sending is complete and the result of each sending. If failed, refer to Error code to figure out its failure cause.

Request

Header
Name Description Required
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.		 O
Path variable
Name Type Description Required
ID Integer Creative ID O
REQUEST_ID String Unique request ID O

Response

Body
Name Type Description
completed Boolean Whether sending multiple messages is complete.
If not complete, completed is false, and results is an empty array.
results PersonalMessageResult[] The result list of each sending request.
PersonalMessageResult
Name Type Description
messageSerialNumber String A unique ID that identifies each sent message.
status String Sending result, one of:
SUCCEEDED
FAILED
statusReason String Sending result detailed reason
sendAt String Date the message was sent, in yyyy-MM-dd HH:mm:ss format.

Sample

Request
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}"
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "completed": true,
    "results": [
        {
            "status": "SUCCEEDED",
            "sendAt": "2023-07-31 16:00:00"
        }
    ]
}

Upload image for personalized message

Basic information
Method URL Authorization
POST https://apis.moment.kakao.com/openapi/v4/messages/personal/images/upload Business token
Permission Prerequisite Business Authentication Business consent items
Required:
Request permission		 Switch to a Biz app
Set Business redirect URI
Business consent items		 Required Required

This API enables you to upload images for Personalized messages. You can upload up to 100 images at once.

Kakao checks the image specification and the policies and saves them into a stable internal repository.

Send a POST request with the Business token and ad account ID in the header.

If the request is successful, the response includes URLs for Personalized messages. If failed, refer to Error code to figure out its failure cause.

Cautions when uploading images

Uploaded images should be included in the message content. If the images are uploaded for other purposes, it is possible to get penalties to ad account. Also recommend uploading images as close to the time of sending the message as possible. The response image URL cannot be used permanently, and the registered image may be deleted without notice due to Kakao's system conditions.

Request

Header
Name Description Required
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.		 O
Body
Name Type Description Required
files Multipart file[] Image files to upload
File format: JPG, JPEG, PNG
Recommended size: 800x400(2:1 ratio), 800x800(1:1 ratio), 800x600(4:3 ratio)
File size: less than 10MB		 O

Response

Body
Name Type Description
successFiles ImageFile[] Uploaded image information
invalidFiles InvalidFile[] Image information and the reason that failed to upload
ImageFile
Name Type Description
downloadUrl String Image URL
originalFileName String Image file name
InvalidFile
Name Type Description
fileName String File name that failed to upload
invalidReasons InvalidReason[] Failure reasons
InvalidReason
Name Type Description
reason String Reason
description String Detail information

Sample

Request
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}"
Response
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"
        }
      ]
    }
  ]
}

Set video for personalized message

Basic information
Method URL Authorization
POST https://apis.moment.kakao.com/openapi/v4/messages/personal/videos/register Business token
Permission Prerequisite Business Authentication Business consent items
Required:
Request permission		 Switch to a Biz app
Set Business redirect URI
Business consent items		 Required Required

This API enables you to set a video on Kakao TV in advance to validate. You can set up to 100 images at once.

You must request by the owner account of the Kakao TV channel.

The videos that are not set by this API cannot be used for Personalized messages.

Send a POST request with the Business token and ad account ID in the header.

If the request is successful, the response includes whether the videos are set or not. If failed, refer to Error code to figure out its failure cause.

Request

Header
Name Description Required
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.		 O
Body
Name Type Description Required
kakaoTVUrls String[] Kakao TV video URLs to set. O

Response

Body
Name Type Description
successVideoUrls String[] Kakao TV video URLs that were successfully set.
invalidKakaoTVUrls InvalidKakaoTV[] Failure reasons
InvalidKakaoTV
Name Type Description
kakaoTVUrl String Kakao TV video URLs that failed to be set.
reason String Reason

Sample

Request
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"]
}'
Response
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 채널에 권한이 없습니다."
    }
  ]
}

See more

Kakao Moment> Personalized message management