This document describes how to use the Message ad operation API for Kakao Moment message ads.

Message ads have different components depending on the message type, so the available parameters differ from each other. For detailed information, refer to Message type components.

Message ads can send the following types of messages. For detailed information on each message type, refer to the Kakao Business Channel Message Guide.

This section provides information about the field path, specifications, and required status for each message type component.

• Divided into intro and carousel (1-6).
• When intro is included, carousel1 is required; when not included, carousel1-2 are required.

• Carousel1-2 required, Carousel3-6 optional.

• Item1-3 required, Item4-7 optional.

• Image
  • Format: JPG, JPEG, PNG
  • Size: Width greater than 80px (recommended: 800x400, 800x800, 800x600)
  • Capacity: 10MB or less
  • Ratio: Width: Height ratio less than 1:2.5 (recommended: 2:1, 1:1, 4:3)

If URLs contain special characters or Korean text that are not encoded in UTF-8, ads may not land properly in the Kakao Talk in-app browser on iOS devices. Below are examples of special characters that may cause landing errors.

• %
• |
• "

Additionally, deep link (Deeplink) format URLs that require parameter and macro substitution are not officially supported.

Saves the message ad content that will be sent from the Kakao Talk Channel.

The availability and required status of parameters differ depending on the message type (type). For related detailed information, refer to Message type components.

Send a POST request with the business token, ad account ID, and Kakao Talk Channel profile ID in the header. If the request is successful, the response includes detailed information of the created message. If failed, see Error code.

• Responds with ResponseMessage object

curl -X POST "https://apis.moment.kakao.com/openapi/message/v2/message-ads/message" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Message_Ad_Test_Basic_Text",
  "ageVerification": false,
  "message": {
    "type": "BASIC_TEXT_MESSAGE",
    "description": "Promotional Text",
    "shareFlag": true,
    "adFlag": true,
    "items": [
      {
        "imageUrl": "https://partner.com/img/message/001.jpg"
      }
    ],
    "buttons": [
      {
        "title": "Button 1 Name",
        "pcLandingUrl": "https://daum.net/1",
        "mobileLandingUrl": "https://daum.net/1"
      },
      {
        "title": "Button 2 Name",
        "pcLandingUrl": "https://daum.net/1",
        "mobileLandingUrl": "https://daum.net/1"
      }
    ],
    "couponBook": {
      "couponBookTitleType": "UPGRADE",
      "couponBookTitle": "Coupon Title",
      "title": "Coupon Detailed Description",
      "pcLandingUrl": "https://daum.net",
      "mobileLandingUrl": "https://daum.net"
    }
  }
}'

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "messageAdId": "msg-ad-1402922220759433217",
  "name": "Message_Ad_Test_Basic_Text",
  "type": "BASIC_TEXT_MESSAGE",
  "description": "Promotional Text",
  "items": [
    {
      "imageUrl": "https://partner.com/img/message/001.jpg"
    }
  ],
  "buttons": [
    {
      "title": "Button 1 Name",
      "pcLandingUrl": "https://daum.net/1",
      "mobileLandingUrl": "https://daum.net/1"
    },
    {
      "title": "Button 2 Name",
      "pcLandingUrl": "https://daum.net/1",
      "mobileLandingUrl": "https://daum.net/1"
    }
  ],
  "couponBook": {
    "title": "Coupon Detailed Description",
    "pcLandingUrl": "https://daum.net",
    "mobileLandingUrl": "https://daum.net",
    "couponBookTitle": "Coupon Title",
    "couponBookTitleType": "UPGRADE"
  },
  "ageVerification": false,
  "adFlag": true,
  "shareFlag": true
}

Modifies the message ad content that will be sent from the Kakao Talk Channel.

The message modification policy is as follows:

• Must be in the same format as the existing message.
• After 5 minutes before the scheduled send time, only the message name can be modified. Other parameters except the name are ignored.
• Images and text that do not match the message execution guide cannot be used.

The availability and required status of parameters differ depending on the message type (type). For related detailed information, refer to Message type components.

Send a PATCH request with the business token, ad account ID, and Kakao Talk Channel profile ID in the header. If the request is successful, the response includes detailed information of the modified message. If failed, see Error code.

• Responds with ResponseMessage object

curl -X PATCH "https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}/message" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MessageAd_Test_Basic_Text",
    "ageVerification": false,
    "message": {
        "type": "BASIC_TEXT_MESSAGE",
        "title": "Promotional text changed",
        "shareFlag": true,
        "adFlag": false,
        "items": [
            {
                "imageUrl": "https://partner.com/img/message/001.jpg"
            }
        ],
        "buttons": [
            {
                "title": "Button 1 Name",
                "pcLandingUrl": "https://daum.net/1",
                "mobileLandingUrl": "https://daum.net/1"
            },
            {
                "title": "Button 2 Name",
                "pcLandingUrl": "https://daum.net/1",
                "mobileLandingUrl": "https://daum.net/1"
            }
        ],
        "couponBook": {
            "couponBookTitleType": "UPGRADE",
            "couponBookTitle": "Coupon Title",
            "title": "Coupon Detail Description",
            "pcLandingUrl": "https://daum.net",
            "mobileLandingUrl": "https://daum.net"
        }
    }
}'

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "messageAdId": "msg-ad-1195179794616258561",
    "name": "MessageAd_Test_Basic_Text",
    "type": "BASIC_TEXT_MESSAGE",
    "title": "Promotional text changed",
    "items": [
        {
            "imageUrl": "https://t1.kakaocdn.net/b2/creative/56493/3912ceec1584f2ec1ccf8fad73145254.jpg"
        }
    ],
    "buttons": [
        {
            "title": "Button 1 Name",
            "pcLandingUrl": "https://daum.net/1",
            "mobileLandingUrl": "https://daum.net/1"
        },
        {
            "title": "Button 2 Name",
            "pcLandingUrl": "https://daum.net/1",
            "mobileLandingUrl": "https://daum.net/1"
        }
    ],
    "couponBook": {
        "title": "Coupon Detail Description",
        "pcLandingUrl": "https://daum.net",
        "mobileLandingUrl": "https://daum.net",
        "couponBookTitle": "Coupon Title",
        "couponBookTitleType": "UPGRADE"
    },
    "ageVerification": false,
    "adFlag": false,
    "shareFlag": true
}

Requests a message test send.

When sending, [Test Send] is added to the promotional text area. Only phone numbers that are friends can be sent, and test sending is limited to 1 time per 30 seconds per user account and ad account.

Send a POST request with the business token, ad account ID, and Kakao Talk Channel profile ID in the header. If the request is successful, there is no response body. If failed, see Error code.

curl -X POST "https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}/send-test" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d '{
        "phoneNumbers": ["014-0042-4549"]
    }'

HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json;charset=UTF-8

Sets the message send start time and send target.

The send start time can be set in 1-minute intervals from 5 minutes after the reservation time. However, since sending starts only after parameter generation is complete, if the start time is set within 1 hour, sending may be delayed depending on the parameter scale.

The send start time can be set from 08:00 to 20:50, and messages that have not been sent after 20:55 are sent after 8 AM the next day.

Message costs differ depending on whether message targeting is set.

• Non-target: Messages without device/targeting information set, 15 won
• Target: Messages with at least 1 device/targeting information set, 20 won (however, 15 won when location type Domestic (domestic only) is set)

Send a POST request with the business token, ad account ID, and Kakao Talk Channel profile ID in the header. If the request is successful, the response includes message ad send reservation information as a JSON object. If failed, see Error code.

Retrieves detailed information about the message ad send reservation.

Send a GET request with the business token, ad account ID, and Kakao Talk Channel profile ID in the header. If the request is successful, the response includes detailed information of the message ad send reservation. If failed, see Error code.

Modifies the message send start time and send target.

Send reservation modification is possible until 5 minutes before the send start time.

Send a PATCH request with the business token, ad account ID, and Kakao Talk Channel profile ID in the header. If the request is successful, the response includes message ad send reservation information as a JSON object. If failed, see Error code.

Retrieves detailed information for location settings used in message ad send reservations.

For the complete list, refer to the Administrative District Type Information CSV file (download).

Send a GET request with the business token, ad account ID, and Kakao Talk Channel profile ID in the header. If the request is successful, the response includes targeting location information. If failed, see Error code.

curl -X GET "https://apis.moment.kakao.com/openapi/message/v2/message-ads/sending-reservation/location" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json"

curl -v -G GET "https://apis.moment.kakao.com/openapi/message/v2/message-ads/sending-reservation/location" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json" \
  -d "codes=A7000A001,Q20000025"

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id": "A",
    "name": "Gangwon Special Self-Governing Province",
    "children": [
        {
            "id": "A7000",
            "name": "Gangneung-si",
            "children": [
                {
                    "id": "A7000A001",
                    "name": "Gangnam-dong"
                }
            ]
        }
        ...
    ],
    ...
}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
    {
        "id": "A7000A001",
        "name": "Gangwon Special Self-Governing Province Gangneung-si Gangnam-dong",
        "deprecated": true
    },
    {
        "id": "Q20000025",
        "name": "Sejong Special Self-Governing City Sejong-si Haemil-dong",
        "deprecated": false
    }
]

Retrieves the available audience and price for sending.

The existing messageAdId setting values are reflected in the lookup or do not affect existing send reservations, and simply refer to the targeting audience and price for the targeting conditions of the API request.

Send a POST request with the business token, ad account ID, and Kakao Talk Channel profile ID in the header. If the request is successful, the response includes targeting audience and price information. If failed, see Error code.

Terminates the message ad.

Messages currently being sent will be stopped, and scheduled messages will be cancelled.

Send a PUT request with the business token, ad account ID, and Kakao Talk Channel profile ID in the header. If the request is successful, the response returns only an HTTP 200 status code without a body. If failed, see Error code.

curl -X PUT "https://apis.moment.kakao.com/openapi/message/v2/message-ads/${MESSAGE_AD_ID}/finish" \
  -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}" \
  -H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
  -H "Content-Type: application/json"

HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json;charset=UTF-8