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

Sends 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

Sends 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

Sends 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

Retrieves sending status.

You can retrieve sending status in 7 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

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

Sets 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 API Reference

사이드 메뉴

Getting started

Kakao Developers

Login

Communication

Kakao Map

Navigation

Advertisement

Search

More

Personalized message management

Test sending personalized message

Basic information

Request

Header

Path variable

Body

Sample

Request

Response

Send a personalized message

Basic information

Request

Header

Path variable

Body

Response

Body

Sample

Request

Response

Send multiple personalized message

Basic information

Request

Header

Path variable

Body

PersonalMessageSendRequest

Response

Body

Sample

Request

Response

Retrieve sending status

Basic information

Request

Header

Path variable

Response

Body

PersonalMessageResult

Sample

Request

Response

Upload image for personalized message

Basic information

Request

Header

Body

Response

Body

ImageFile

InvalidFile

InvalidReason

Sample

Request

Response

Set video for personalized message

Basic information

Request

Header

Body

Response

Body

InvalidKakaoTV

Sample

Request

Response

See more

Was this helpful?