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 creative under a Personalized Message X Reach campaign.

The message includes [Test Send] in the promotional text area.

Rate limit

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 creative under a Personalized Message X Reach campaign to one user.

Conditions for use

Can only send to one user at a time
Single-message sending is processed synchronously

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 creative under a Personalized Message X Reach campaign to multiple users.

Conditions for use

Can request from 2 to 100 messages at a time
Responds immediately if the request includes an invalid value
Multi-message sending that passes validation is processed asynchronously

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

Returns the result of a Personalized Message send request.

You can retrieve sending status in 7 days from the request.

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.

Image upload conditions

You can upload from 1 to 100 images at once.

Kakao validates the images against the applicable specifications and policies before saving them.

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 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=@image.jpg"

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

See more

Kakao Moment API Reference

사이드 메뉴

Docs Home

Getting started

Kakao Developers

Login

Communication

Map

Navigation

Advertisement

Search

More

Personalized message management

Test sending personalized message

Basic information

Rate limit

Request

Header

Path variable

Body

Sample

Request

Response

Send a personalized message

Basic information

Conditions for use

Request

Header

Path variable

Body

Response

Body

Sample

Request

Response

Send multiple personalized message

Basic information

Conditions for use

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

Image upload conditions

Request

Header

Body

Response

Body

ImageFile

InvalidFile

InvalidReason

Sample

Request

Response

See more

Was this helpful?