bizgo Developers
API ReferenceCommunication APIKakao Biz Message

Brand Message

Brand Message is the Kakao Biz Message channel for sending brand-style messages to KakaoTalk channel friends. It supports both template-based basic sends and free-form sends where you compose the message content yourself.

Send a basic Brand Message

A basic Brand Message is sent against a template you registered in advance. You can use it for template-code-based substitution sends.

Send a basic message

POST/api/comm/v1/send/omni
Try sending a messageTry it in the Sandbox

The basic Brand Message send specification. It uses a pre-approved template code, and sendType is basic.

There are two ways to send a basic message.
1. Variable separation: put the substitution values in Variable fields such as messageVariable, buttonVariable, and couponVariable.
2. Payload: put the values directly into the text, attachment, and carousel structures, similar to Alimtalk.

The two are alternatives within the same basic send, and you must use the fields that match the template structure and msgType. Use Variable fields only when you need variable substitution.

Body Parameters

{}JSON

destinations

RequiredObject Array

The array of recipient information. Up to 200 per broadcast send.

messageFlow

RequiredObject Array

When you add messages, they are handled in order as automatic failover messages.

paymentCode

String

The department code used for settlement.

groupKey

String

A key you set to group messages and review their statistics in Message Insight.

idempotencyKey

String

The idempotency key field that identifies the request for idempotency.

idempotencyTtl

Integer

The validity period of the idempotency key.

ref

String

A per-request reference field.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X POST "/api/comm/v1/send/omni" \
2 -H "Authorization: {ApiKey}" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "destinations": [{ "to": "01012345678", "messageVariable": { "name": "ํ™๊ธธ๋™" } }],
6 "messageFlow": [{
7 "brandmessage": {
8 "sendType": "basic",
9 "msgType": "TEXT",
10 "senderKey": "{senderKey}",
11 "templateCode": "BM_TEMPLATE_001"
12 }
13 }],
14 "ref": "brand-basic-20260331-001"
15 }'

Response example

1{
2 "common": {
3 "authCode": "A000",
4 "authResult": "Success",
5 "infobankTrId": "Infobank-Tracking-Id"
6 },
7 "data": {
8 "code": "A000",
9 "result": "SUCCESS",
10 "data": {
11 "destinations": [{
12 "to": "01012345678",
13 "msgKey": "20260424104234546POM101182450000",
14 "code": "A000",
15 "result": "Success"
16 }]
17 },
18 "ref": "brand-basic-20260331-001"
19 }
20}

Basic reservation send

POST/api/comm/v1/reservation

Registers a basic Brand Message to be sent at the specified time. The detailed fields you can send are the same as in the basic message send specification. After registering, see the Reservation management page for lookup, update, cancel, pause, resume, and recipient management.

Body Parameters

{}JSON

destinations

RequiredObject Array

The array of recipient information. Up to 200 per broadcast send.

messageFlow

RequiredObject Array

When you add messages, they are handled in order as automatic failover messages.

resvSendTime

RequiredString

The reservation send time.

resvName

String

A name that identifies the reservation.

ref

String

A per-request reference field.

Returns

common

Object

The common response section.

data

Object

The reservation registration response section.

Request example

1curl -X POST "https://mars.ibapi.kr/api/comm/v1/reservation" \
2 -H "Authorization: {ApiKey}" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "destinations": [{
6 "to": "01012345678"
7 }],
8 "messageFlow": [{
9 "brandmessage": {
10 "sendType": "basic",
11 "msgType": "FT",
12 "senderKey": "{senderKey}",
13 "templateCode": "BM_TEMPLATE_001",
14 "targeting": "M"
15 }
16 }],
17 "resvSendTime": "2026-05-01 10:00:00",
18 "resvName": "๋ธŒ๋žœ๋“œ๋ฉ”์‹œ์ง€ ๊ธฐ๋ณธํ˜• ์˜ˆ์•ฝ ๋ฐœ์†ก",
19 "ref": "brand-basic-resv-20260501-001"
20 }'

Response example

1{
2 "common": {
3 "authCode": "A000",
4 "authResult": "Success",
5 "infobankTrId": "Infobank-Tracking-Id"
6 },
7 "data": {
8 "code": "A000",
9 "result": "Success",
10 "resvKey": "20260501100000RESV0000000001"
11 }
12}

Basic send with automatic template substitution

POST/api/comm/v1/send/omni
Try sending a messageTry it in the Sandbox

Sends a basic Brand Message using only a template code and substitution variables, without a template payload. The Bizgo API builds the payload that matches the template code and substitutes the destinations[].replaceWords values before sending.

Body Parameters

{} JSON

destinations

RequiredObject Array

The array of recipient information.

messageFlow

RequiredObject Array

The array of message specifications.

paymentCode

String

The department code used for settlement.

groupKey

String

The group key.

idempotencyKey

String

The idempotency key.

idempotencyTtl

Integer

The idempotency key expiration time in seconds.

ref

String

A per-request reference field.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X POST "https://mars.ibapi.kr/api/comm/v1/send/omni" \
2 -H "Authorization: {ApiKey}" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "destinations": [{
6 "to": "01000000000",
7 "replaceWords": {
8 "customerName": "ํ™๊ธธ๋™",
9 "point": "500"
10 }
11 }],
12 "messageFlow": [{
13 "brandmessage": {
14 "senderKey": "{senderKey}",
15 "templateCode": "{templateCode}",
16 "sendType": "template",
17 "targeting": "I",
18 "pushAlarm": "Y",
19 "originCID": "123456789",
20 "unsubscribePhoneNumber": "0801234567",
21 "unsubscribeAuthNumber": "12345"
22 }
23 }],
24 "paymentCode": "brand-team-01",
25 "groupKey": "brand-template-group-01",
26 "idempotencyKey": "brand-template-idempotency-001",
27 "idempotencyTtl": 300,
28 "ref": "brand-template-001"
29 }'

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "destinations": [{
12 "to":"01000000000",
13 "msgKey":"20260424104234546POM101182450000",
14 "code":"A000",
15 "result":"Success"
16 }]
17 },
18 "ref":"brand-template-001"
19 }
20}

Send a free-form Brand Message

A free-form Brand Message is sent with content you compose directly, without registering a template. You can define the image, button, and carousel elements that suit the message type.

About discountRate (discount rate) for commerce and carousel commerce

  • Allowed range: 1 to 100
  • From 2026-08-04, a discountRate value of 0 makes the template registration or send request fail.
  • The same applies to discount_rate in free-form sends and to the fixed variable ํ• ์ธ์œจ ("discount rate") in the variable-separation method.
  • When you are not using a discount rate, send null instead of 0.

Send a free-form message

POST/api/comm/v1/send/omni
Try sending a messageTry it in the Sandbox

The free-form Brand Message send specification. You compose the body and button values directly without a template code, and sendType is free.

Body Parameters

{}JSON

destinations

RequiredObject Array

The array of recipient information. Up to 200 per broadcast send.

messageFlow

RequiredObject Array

When you add messages, they are handled in order as automatic failover messages.

paymentCode

String

The department code used for settlement.

groupKey

String

A key you set to group messages and review their statistics in Message Insight.

idempotencyKey

String

The idempotency key field that identifies the request for idempotency.

idempotencyTtl

Integer

The validity period of the idempotency key.

ref

String

A per-request reference field.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X POST "/api/comm/v1/send/omni" \
2 -H "Authorization: {ApiKey}" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "destinations": [{ "to": "01012345678" }],
6 "messageFlow": [{
7 "brandmessage": {
8 "sendType": "free",
9 "msgType": "TEXT",
10 "senderKey": "{senderKey}",
11 "content": "์ž์œ ํ˜• ๋ธŒ๋žœ๋“œ๋ฉ”์‹œ์ง€ ๋ณธ๋ฌธ์ž…๋‹ˆ๋‹ค."
12 }
13 }],
14 "ref": "brand-free-20260331-001"
15 }'

Response example

1{
2 "common": {
3 "authCode": "A000",
4 "authResult": "Success",
5 "infobankTrId": "Infobank-Tracking-Id"
6 },
7 "data": {
8 "code": "A000",
9 "result": "SUCCESS",
10 "data": {
11 "destinations": [{
12 "to": "01012345678",
13 "msgKey": "20260424104234546POM101182450000",
14 "code": "A000",
15 "result": "Success"
16 }]
17 },
18 "ref": "brand-free-20260331-001"
19 }
20}

Free-form reservation send

POST/api/comm/v1/reservation

Registers a free-form Brand Message to be sent at the specified time. The detailed fields you can send are the same as in the free-form message send specification. After registering, see the Reservation management page for lookup, update, cancel, pause, resume, and recipient management.

Body Parameters

{}JSON

destinations

RequiredObject Array

The array of recipient information. Up to 200 per broadcast send.

messageFlow

RequiredObject Array

When you add messages, they are handled in order as automatic failover messages.

resvSendTime

RequiredString

The reservation send time.

resvName

String

A name that identifies the reservation.

ref

String

A per-request reference field.

Returns

common

Object

The common response section.

data

Object

The reservation registration response section.

Request example

1curl -X POST "https://mars.ibapi.kr/api/comm/v1/reservation" \
2 -H "Authorization: {ApiKey}" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "destinations": [{
6 "to": "01012345678"
7 }],
8 "messageFlow": [{
9 "brandmessage": {
10 "sendType": "free",
11 "msgType": "FT",
12 "senderKey": "{senderKey}",
13 "content": "์ž์œ ํ˜• ๋ธŒ๋žœ๋“œ๋ฉ”์‹œ์ง€ ์˜ˆ์•ฝ ๋ฐœ์†ก ๋ณธ๋ฌธ์ž…๋‹ˆ๋‹ค.",
14 "targeting": "M"
15 }
16 }],
17 "resvSendTime": "2026-05-01 10:00:00",
18 "resvName": "๋ธŒ๋žœ๋“œ๋ฉ”์‹œ์ง€ ์ž์œ ํ˜• ์˜ˆ์•ฝ ๋ฐœ์†ก",
19 "ref": "brand-free-resv-20260501-001"
20 }'

Response example

1{
2 "common": {
3 "authCode": "A000",
4 "authResult": "Success",
5 "infobankTrId": "Infobank-Tracking-Id"
6 },
7 "data": {
8 "code": "A000",
9 "result": "Success",
10 "resvKey": "20260501100000RESV0000000001"
11 }
12}

Basic Brand Message broadcast send

This capability sends a basic template message in bulk to a friend group or to all friends. It also provides send control (resume, pause, terminate) and status lookup. To check the expected audience size and the estimated duration before you send, see Pre-send checks for Brand Message.

Broadcast send

Notes on broadcast sends

  • The template you use for the send must have no variables, and the template status must be registered (A).
  • The send runs automatically at the broadcast message start time you requested; it stops automatically from 20:50 to 08:00 the next day and resumes automatically after 08:00 the next day.
  • If you use a friend group, the group status must be C (Completed) and the number of registered users in the group (user_count) must be 10 or more before you can schedule a message send.
  • Friend relationships inside a friend group are synchronized in real time.
  • Both all-friends sends and friend group sends set the send count from the friend relationships at the time of the send request, and messages are then sent sequentially within that set count according to the friend relationships at the actual send time.
POST/api/comm/v1/center/brandmessage/groupMessage
Try sending a messageTry it in the Sandbox

Schedules a broadcast send to an entire Kakao friend group based on a basic template. You can set the start time to at least 10 minutes after the request, within the 08:00โ€“20:50 (KST) window.

Body Parameters

{} JSON

brandmessage

RequiredObject

The basic template broadcast send information.

paymentCode

String

The department code used for settlement.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupMessage" \
2 -H "Authorization: {ApiKey}" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "brandmessage": {
6 "senderKey": "{senderKey}",
7 "templateCode": "{templateCode}",
8 "friendGroupKey": "{friendGroupKey}",
9 "sendStartAt": "2026-04-08 16:40:00",
10 "pushAlarm": "Y"
11 }
12 }'

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "brandmessage": {
12 "requestId":"1203981",
13 "status":"READY",
14 "sendStartAt":"2026-04-08 16:40:00",
15 "pushAlarm":"Y",
16 "expectedCount": 7,
17 "sendCount": 0,
18 "senderKey":"{senderKey}",
19 "msgType":"FI",
20 "templateCode":"{templateCode}"
21 }
22 }
23 }
24}

Resume a broadcast send

POST/api/comm/v1/center/brandmessage/groupMessage/resume
Try it in the Sandbox

Resumes a paused basic template broadcast send request.

Body Parameters

{} JSON

brandmessage

RequiredObject

The broadcast send control information.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupMessage/resume" \
2 -H "Authorization: {ApiKey}" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "brandmessage": {
6 "senderKey": "{senderKey}",
7 "requestId": "1203981"
8 }
9 }'

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "brandmessage": {
12 "requestId":"1203981",
13 "status":"READY",
14 "sendStartAt":"2026-04-08 16:20:00",
15 "pushAlarm":"Y",
16 "expectedCount": 7,
17 "sendCount": 0,
18 "senderKey":"{senderKey}",
19 "msgType":"FI",
20 "templateCode":"{templateCode}"
21 }
22 }
23 }
24}

Pause a broadcast send

POST/api/comm/v1/center/brandmessage/groupMessage/pause
Try it in the Sandbox

Pauses a basic template broadcast send request that is in progress.

Body Parameters

{} JSON

brandmessage

RequiredObject

The broadcast send control information.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupMessage/pause" \
2 -H "Authorization: {ApiKey}" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "brandmessage": {
6 "senderKey": "{senderKey}",
7 "requestId": "1203981"
8 }
9 }'

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "brandmessage": {
12 "requestId":"1203981",
13 "status":"PAUSED",
14 "sendStartAt":"2026-04-08 16:20:00",
15 "pushAlarm":"Y",
16 "expectedCount": 7,
17 "sendCount": 3,
18 "senderKey":"{senderKey}",
19 "msgType":"FI",
20 "templateCode":"{templateCode}"
21 }
22 }
23 }
24}

Terminate a broadcast send

POST/api/comm/v1/center/brandmessage/groupMessage/terminate
Try it in the Sandbox

Terminates a basic template broadcast send request that is reserved or in progress.

Body Parameters

{} JSON

brandmessage

RequiredObject

The broadcast send control information.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupMessage/terminate" \
2 -H "Authorization: {ApiKey}" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "brandmessage": {
6 "senderKey": "{senderKey}",
7 "requestId": "1203981"
8 }
9 }'

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "brandmessage": {
12 "requestId":"1203981",
13 "status":"TERMINATED",
14 "sendStartAt":"2026-04-08 16:20:00",
15 "pushAlarm":"Y",
16 "expectedCount": 7,
17 "sendCount": 3,
18 "senderKey":"{senderKey}",
19 "msgType":"FI",
20 "templateCode":"{templateCode}"
21 }
22 }
23 }
24}

Look up a broadcast send

GET/api/comm/v1/center/brandmessage/groupMessage
Try it in the Sandbox

Looks up the status of a specific broadcast send request by sender profile key and request ID.

Query Parameters

senderKey

RequiredString

The sender profile key.

requestId

RequiredInteger

The broadcast send request ID.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupMessage?senderKey={senderKey}&requestId=1203981" \
2 -H "Authorization: {ApiKey}"

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "brandmessage": {
12 "requestId":"1203981",
13 "status":"SENDING",
14 "sendStartAt":"2026-04-08 16:40:00",
15 "pushAlarm":"Y",
16 "expectedCount": 7,
17 "sendCount": 3,
18 "senderKey":"{senderKey}",
19 "msgType":"FI",
20 "templateCode":"{templateCode}"
21 }
22 }
23 }
24}

Look up the list of recently changed broadcast send requests

GET/api/comm/v1/center/brandmessage/groupMessage/lastModified
Try it in the Sandbox

Looks up the broadcast send request IDs changed after the reference time. Use it to reconcile request statuses you missed.

Query Parameters

senderKey

RequiredString

The sender profile key.

since

String

The reference time for changes.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupMessage/lastModified?senderKey={senderKey}&since=2026-04-08T15:00:00" \
2 -H "Authorization: {ApiKey}"

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "brandmessage": {
12 "requestIds": ["1203981", "1203982", "1203983"]
13 }
14 }
15 }
16}

Pre-send checks for Brand Message

These lookups let you check the expected send count and charge, the number of friends you hold, and the estimated duration before you send. They support both friend-group-based and phone-number-list-based checks, and you use them not only for broadcast sends but also to validate any send in advance.

Check the expected audience size (friend group based)

GET/api/comm/v1/center/brandmessage/groupMessage/possible
Try it in the Sandbox

Looks up the estimated number of sends for a broadcast based on the message type and friend group conditions. When you use a friend group, its status must be complete (C) and it must contain at least 10 registered users to schedule a send; friend relationships are synced in real time.

Query Parameters

senderKey

RequiredString

The sender profile key.

msgType

RequiredString

The Brand Message type. (Converted to Kakao's original chatBubbleType.)

friendGroupKey

String

The target friend group key. If omitted, the lookup covers all friends.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupMessage/possible?senderKey={senderKey}&msgType=FI&friendGroupKey={friendGroupKey}" \
2 -H "Authorization: {ApiKey}"

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "brandmessage": {
12 "possible": 320
13 }
14 }
15 }
16}

Check the expected audience size (phone number list based)

POST/api/comm/v1/center/brandmessage/groupMessage/friend/possible
Try it in the Sandbox

Looks up the estimated number of eligible sends for a broadcast based on a phone number list. Country codes in the list are normalized automatically, and the eligible audience is calculated from the valid numbers. You need at least 10 entries, and the whole request is rejected if any entry is malformed.

Body Parameters

{} JSON

senderKey

RequiredString

The sender profile key.

phoneNumbers

RequiredString Array

The list of phone numbers to check for send eligibility.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupMessage/friend/possible" \
2 -H "Authorization: {ApiKey}" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "senderKey": "{senderKey}",
6 "phoneNumbers": [
7 "01000000000",
8 "01000000001"
9 ]
10 }'

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "brandmessage": {
12 "possible": 320
13 }
14 }
15 }
16}

Look up the total friend count for the channel

GET/api/comm/v1/center/brandmessage/groupMessage/friendCount
Try it in the Sandbox

Looks up the friend count for the sender profile. Use it to check the eligible audience size for a broadcast send in advance.

Query Parameters

senderKey

RequiredString

The sender profile key.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupMessage/friendCount?senderKey={senderKey}" \
2 -H "Authorization: {ApiKey}"

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "brandmessage": {
12 "count": 1250
13 }
14 }
15 }
16}

Look up the estimated duration

GET/api/comm/v1/center/brandmessage/groupMessage/estimate
Try it in the Sandbox

Looks up the estimated end time and duration based on the broadcast send start time and audience size.

Query Parameters

senderKey

RequiredString

The sender profile key.

startTime

RequiredString

The broadcast send start time.

count

RequiredInteger

The send audience size.

target

String

The target type.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupMessage/estimate?senderKey={senderKey}&startTime=2026-04-08T16:40:00&count=320&target=FRIEND_GROUP" \
2 -H "Authorization: {ApiKey}"

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "brandmessage": {
12 "estimatedFinishedAt":"2026-04-08T16:58:00",
13 "duration": 18
14 }
15 }
16 }
17}

Manage image files

Upload the image files you will use in Brand Message templates and free-form message composition. The upload path differs by message type and layout.

Upload an image

POST/api/comm/v1/file/brandmessage/default
Try it in the Sandbox

Uploads an image used in a basic Brand Message. This API does not attach a file directly to the message body โ€” it issues an image URL you use when registering and composing a Brand Message template.

Body Parameters

FORM-DATA

file

RequiredBinary

The binary of the Brand Message image file to upload.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X POST "https://mars.ibapi.kr/api/comm/v1/file/brandmessage/default" \
2 -H "Authorization: {ApiKey}" \
3 -F "file=@/path/brand-image.jpg"

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "imgUrl":"https://example.kakao.image/brand-image.jpg"
12 }
13 }
14}

Upload a wide image

POST/api/comm/v1/file/brandmessage/wide
Try it in the Sandbox

Uploads an image used in a wide image Brand Message. Use the issued imgUrl in the Brand Message template or send configuration.

Body Parameters

FORM-DATA

file

RequiredBinary

The binary of the Brand Message image file to upload.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X POST "https://mars.ibapi.kr/api/comm/v1/file/brandmessage/wide" \
2 -H "Authorization: {ApiKey}" \
3 -F "file=@/path/brand-image.jpg"

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "imgUrl":"https://example.kakao.image/brand-image.jpg"
12 }
13 }
14}

Upload the first wide list image

POST/api/comm/v1/file/brandmessage/wideItemList/first
Try it in the Sandbox

Uploads the image used for the first list image of a wide list Brand Message.

Body Parameters

FORM-DATA

file

RequiredBinary

The binary of the Brand Message image file to upload.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X POST "https://mars.ibapi.kr/api/comm/v1/file/brandmessage/wideItemList/first" \
2 -H "Authorization: {ApiKey}" \
3 -F "file=@/path/brand-image.jpg"

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "imgUrl":"https://example.kakao.image/brand-image.jpg"
12 }
13 }
14}

Upload a wide list image

POST/api/comm/v1/file/brandmessage/wideItemList
Try it in the Sandbox

Uploads the image used for the 2ndโ€“4th list images of a wide list Brand Message.

Body Parameters

FORM-DATA

file

RequiredBinary

The binary of the Brand Message image file to upload.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X POST "https://mars.ibapi.kr/api/comm/v1/file/brandmessage/wideItemList" \
2 -H "Authorization: {ApiKey}" \
3 -F "file=@/path/brand-image.jpg"

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "imgUrl":"https://example.kakao.image/brand-image.jpg"
12 }
13 }
14}
POST/api/comm/v1/file/brandmessage/carouselFeed
Try it in the Sandbox

Uploads an image used in a carousel feed Brand Message.

Body Parameters

FORM-DATA

file

RequiredBinary

The binary of the Brand Message image file to upload.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X POST "https://mars.ibapi.kr/api/comm/v1/file/brandmessage/carouselFeed" \
2 -H "Authorization: {ApiKey}" \
3 -F "file=@/path/brand-image.jpg"

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "imgUrl":"https://example.kakao.image/brand-image.jpg"
12 }
13 }
14}
POST/api/comm/v1/file/brandmessage/carouselCommerce
Try it in the Sandbox

Uploads an image used in a carousel commerce Brand Message. All carousel images must use the same ratio.

Body Parameters

FORM-DATA

file

RequiredBinary

The binary of the Brand Message image file to upload.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X POST "https://mars.ibapi.kr/api/comm/v1/file/brandmessage/carouselCommerce" \
2 -H "Authorization: {ApiKey}" \
3 -F "file=@/path/brand-image.jpg"

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "imgUrl":"https://example.kakao.image/brand-image.jpg"
12 }
13 }
14}

Manage videos

Register the videos you will use in Brand Message and look up their processing status. There are two ways to prepare a video for sending.

  • New upload โ€” a video you have not yet uploaded to Kakao. This is a 2-step structure: you are issued an upload channel, then your client uploads the file directly to that channel. (Unlike the image file management APIs, the file is not transmitted to us directly.)
  • Register an existing video โ€” a video that is already on the channel. You register it for sending with just the vid or the videoUrl, with no re-upload.

New upload flow

TEXT
1. Register the upload  POST /video/upload/register
   โ†’ the response issues vid, uploadUrl, and token
              โ”‚
              โ–ผ
2. Transmit the file    client โ†’ uploadUrl (sent directly to the Kakao server, using token)
              โ”‚
              โ–ผ
3. Check the status     GET /video?vid=...
   โ†’ sendable once status is PUBLIC (PRIVATE allows template registration only)

The A000 in the step 1 response only means the upload channel was issued successfully; it does not mean the video registration is complete. Check whether it is actually usable with the status from the step 3 lookup.

Step 2: transmit the video file

Transmit the video file directly to the uploadUrl you received in the step 1 response. The uploadUrl and the token are valid for only 5 minutes after issue, and if the transmission fails you must start again from the upload registration (step 1).

ItemValue
Method and URLPOST {uploadUrl}
Headersx-kamp-upload-token: {token} ยท Content-Type: multipart/form-data
Bodyfile โ€” the video binary
Bash
curl -X POST \
  -H 'x-kamp-upload-token: {token}' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@{video_file}' \
  '{uploadUrl}'

This transmission goes directly to the Kakao upload server and does not pass through the Bizgo API. Use the vid from the success response to run the step 3 status lookup. If it fails, the errCode and message in the response tell you the cause (nonexistent vid, size, resolution, or length exceeded, unsupported format, token authentication failure, and so on).

Rules for registering an existing video

A video you have already uploaded to your KakaoTalk channel skips step 2 above; you register it straight away by specifying only the vid or the videoUrl.

  • One is required โ€” enter at least one of vid and videoUrl. If you enter both, videoUrl takes precedence.
  • videoUrl format โ€” https://business.kakao.com/{์ฑ„๋„์‹๋ณ„์ž}/videos/{vid}
  • Registrable states โ€” you can only register a video in the PUBLIC or PRIVATE state.

Video status codes

These are the status values in the lookup and registration responses.

statusDescription
REGISTEREDUpload registered
ENCODINGEncoding in progress
PUBLICPublic โ€” can be sent and registered in a template
PRIVATEPrivate โ€” can be registered in a template only
VIOLATEDVideo that violates policy
ILLEGALIllegally filmed material (๋ถˆ๋ฒ•์ดฌ์˜๋ฌผ)
DELETEDDeleted video
ERRORAn error occurred during upload or encoding

Register a video upload

POST/api/comm/v1/center/brandmessage/video/upload/register
Try it in the Sandbox

Registers a video upload for a Brand Message and issues Kakao upload channel information. This API only issues the upload channel โ€” you must send the file yourself to the uploadUrl returned in the response.

Body Parameters

{} JSON

senderKey

RequiredString

The sender profile key. max: 40

fileName

RequiredString

The name of the video file to upload.

fileSize

RequiredNumber

The size of the video file to upload. Unit: bytes

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/video/upload/register" \
2 -H "Authorization: {ApiKey}" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "senderKey": "{senderKey}",
6 "fileName": "brand-promotion.mp4",
7 "fileSize": 4075447
8 }'

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "brandmessage": {
12 "video": {
13 "vid":"rvuzx2fkv08xrgrrhuwsc151z",
14 "uploadUrl":"https://up03-kamp.kakao.com/v4/upload/rvuzx2fkv08xrgrrhuwsc151z/open",
15 "token":"zXupsa4sM18oTL-..."
16 }
17 }
18 }
19 }
20}

Register an existing video

POST/api/comm/v1/center/brandmessage/video/register
Try it in the Sandbox

Registers a video already uploaded to your KakaoTalk channel for Brand Message sending, without re-uploading it. This is a separate API from the video upload registration that issues an upload channel, and you identify the video with either vid or videoUrl โ€” not both.

Body Parameters

{} JSON

senderKey

RequiredString

The sender profile key. max: 40

vid

String

The video identifier to register. Cannot be used together with videoUrl.

videoUrl

String

The channel video URL to register. Cannot be used together with vid.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/video/register" \
2 -H "Authorization: {ApiKey}" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "senderKey": "{senderKey}",
6 "vid": "rvhyrk8x0dqp0d8oiyc1w2m9t"
7 }'

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "brandmessage": {
12 "video": {
13 "vid":"rvhyrk8x0dqp0d8oiyc1w2m9t",
14 "status":"PUBLIC",
15 "title":"๋„์‹œ",
16 "thumbnailUrl":"https://thumb.kakaocdn.net/.../2.jpg",
17 "videoUrl":"https://business.kakao.com/_jIxmCs/videos/1090870"
18 }
19 }
20 }
21 }
22}

Look up a video

GET/api/comm/v1/center/brandmessage/video
Try it in the Sandbox

Looks up the processing status and metadata of a single uploaded video by its identifier.

Query Parameters

vid

RequiredString

The identifier of the video to look up.

senderKey

RequiredString

The sender profile key. max: 40

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/video?vid={vid}&senderKey={senderKey}" \
2 -H "Authorization: {ApiKey}"

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "brandmessage": {
12 "video": {
13 "vid":"rvuzx2fkv08xrgrrhuwsc151z",
14 "status":"PUBLIC",
15 "title":"brand-promotion",
16 "thumbnailUrl":"https://thumb.kakaocdn.net/.../2.jpg",
17 "videoUrl":"https://business.kakao.com/_jIxmCs/videos/1079462"
18 }
19 }
20 }
21 }
22}

Look up the video list

GET/api/comm/v1/center/brandmessage/video/list
Try it in the Sandbox

Looks up the history of videos uploaded for the sender profile. You can filter by registration date and page through the results with offset and limit.

Query Parameters

senderKey

RequiredString

The sender profile key. max: 40

date

String

The registration date to look up. If omitted, all records are returned. Format: yyyyMMdd

offset

Number

The lookup start offset. Negative values are not allowed. default: 0

limit

Number

The number of records to look up. default: 100, max: 1000

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/video/list?senderKey={senderKey}&date=20260624&offset=0&limit=100" \
2 -H "Authorization: {ApiKey}"

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "offset": 0,
12 "limit": 100,
13 "totalCount": 1,
14 "videos": [{
15 "vid":"rvuzx2fkv08xrgrrhuwsc151z",
16 "senderKey":"{senderKey}",
17 "fileName":"brand-promotion.mp4",
18 "fileSize": 4075447,
19 "status":"PUBLIC",
20 "title":"brand-promotion",
21 "thumbnailUrl":"https://thumb.kakaocdn.net/.../2.jpg",
22 "videoUrl":"https://business.kakao.com/_jIxmCs/videos/1079462",
23 "modifiedAt":"2026-06-24 15:53:05",
24 "regDate":"2026-06-24 15:52:29",
25 "updateDate":"2026-06-24 15:53:05"
26 }]
27 }
28 }
29}

Manage basic templates

Look up, register, update, and delete the templates you use for basic Brand Message sends. For types that need an image, issue the imgUrl first with the image file management APIs, then use it.

Look up a template

GET/api/comm/v1/center/brandmessage/template
Try it in the Sandbox

Looks up Brand Message template details by sender profile key and template code.

Query Parameters

senderKey

RequiredString

The sender profile key.

templateCode

RequiredString

The template code.

sendType

String

The Brand Message send type.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/template?senderKey={senderKey}&templateCode={templateCode}&sendType=basic" \
2 -H "Authorization: {ApiKey}"

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "brandmessage": {
12 "senderKey":"{senderKey}",
13 "sendType":"basic",
14 "templateCode":"{templateCode}",
15 "msgType":"FT",
16 "text":"#{customerName}๋‹˜, ํ˜œํƒ์„ ํ™•์ธํ•ด ์ฃผ์„ธ์š”.",
17 "pushAlarm":"Y",
18 "createAt":"2026-04-24T10:42:34+09:00",
19 "modifiedAt":"2026-04-24T10:42:34+09:00",
20 "status":"A"
21 }
22 }
23 }
24}

Look up recently changed templates

GET/api/comm/v1/center/brandmessage/template/lastModified
Try it in the Sandbox

Looks up Brand Message templates changed after the specified time. Use it as the basis for refreshing templates or for an internal sync batch.

Query Parameters

senderKey

RequiredString

The sender profile key.

senderKeyType

String

The sender key type.

since

String

The lookup start time.

page

Integer

The page number.

count

Integer

The number of records per page.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/template/lastModified?senderKey={senderKey}&senderKeyType=S&since=2026-04-23T09:00:00&page=1&count=100" \
2 -H "Authorization: {ApiKey}"

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "brandmessage": {
12 "templates": [{
13 "senderKey":"{senderKey}",
14 "senderKeyType":"S",
15 "templateCode":"BRAND_TEXT_001"
16 }]
17 }
18 }
19 }
20}

Register a template

POST/api/comm/v1/center/brandmessage/template
Try it in the Sandbox

Registers a Brand Message template. For types that require an image, use the imgUrl issued by the Brand Message image upload API.

Body Parameters

{} JSON

brandmessage

RequiredObject

The Brand Message template information.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/template" \
2 -H "Authorization: {ApiKey}" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "brandmessage": {
6 "senderKey": "{senderKey}",
7 "sendType": "basic",
8 "templateName": "๋ธŒ๋žœ๋“œ ํ˜œํƒ ์•ˆ๋‚ด",
9 "msgType": "FT",
10 "text": "#{customerName}๋‹˜, ์ƒˆ๋กœ์šด ํ˜œํƒ์„ ํ™•์ธํ•ด ์ฃผ์„ธ์š”.",
11 "pushAlarm": "Y"
12 }
13 }'

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "brandmessage": {
12 "senderKey":"{senderKey}",
13 "sendType":"basic",
14 "templateCode":"BRAND_TEXT_001",
15 "msgType":"FT",
16 "text":"#{customerName}๋‹˜, ์ƒˆ๋กœ์šด ํ˜œํƒ์„ ํ™•์ธํ•ด ์ฃผ์„ธ์š”.",
17 "pushAlarm":"Y",
18 "createAt":"2026-04-24T10:42:34+09:00",
19 "modifiedAt":"2026-04-24T10:42:34+09:00",
20 "status":"A"
21 }
22 }
23 }
24}

Update a template

PUT/api/comm/v1/center/brandmessage/template
Try it in the Sandbox

Updates a registered Brand Message template. What you can change depends on the review status and Kakao's policy.

Body Parameters

{} JSON

brandmessage

RequiredObject

The Brand Message template information.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X PUT "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/template" \
2 -H "Authorization: {ApiKey}" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "brandmessage": {
6 "senderKey": "{senderKey}",
7 "sendType": "basic",
8 "templateName": "๋ธŒ๋žœ๋“œ ํ˜œํƒ ์•ˆ๋‚ด ์ˆ˜์ •",
9 "msgType": "FT",
10 "text": "#{customerName}๋‹˜, ์—…๋ฐ์ดํŠธ๋œ ํ˜œํƒ์„ ํ™•์ธํ•ด ์ฃผ์„ธ์š”.",
11 "pushAlarm": "Y"
12 }
13 }'

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "brandmessage": {
12 "senderKey":"{senderKey}",
13 "sendType":"basic",
14 "templateCode":"BRAND_TEXT_001",
15 "msgType":"FT",
16 "text":"#{customerName}๋‹˜, ์—…๋ฐ์ดํŠธ๋œ ํ˜œํƒ์„ ํ™•์ธํ•ด ์ฃผ์„ธ์š”.",
17 "pushAlarm":"Y",
18 "createAt":"2026-04-24T10:42:34+09:00",
19 "modifiedAt":"2026-04-24T10:42:34+09:00",
20 "status":"A"
21 }
22 }
23 }
24}

Delete a template

DELETE/api/comm/v1/center/brandmessage/template/senderKey/{senderKey}/templateCode/{templateCode}
Try it in the Sandbox

Deletes a Brand Message template by sender profile key and template code.

Path Parameters

senderKey

RequiredString

The sender profile key.

templateCode

RequiredString

The code of the template to delete.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X DELETE "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/template/senderKey/{senderKey}/templateCode/{templateCode}" \
2 -H "Authorization: {ApiKey}"

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success"
10 }
11}

Manage group tags

A group tag is management information for classifying Brand Message templates and operational targets. You can look up, register, update, and delete group tags by sender profile.

Look up all group tags

GET/api/comm/v1/center/brandmessage/groupTag/list
Try it in the Sandbox

Looks up all Brand Message group tags for the sender profile.

Query Parameters

senderKey

RequiredString

The sender profile key.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupTag/list?senderKey={senderKey}" \
2 -H "Authorization: {ApiKey}"

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "groupTags": [{
12 "groupTagKey":"{groupTagKey}",
13 "groupTagName":"VIP ๊ณ ๊ฐ"
14 }]
15 }
16 }
17}

Look up a group tag

GET/api/comm/v1/center/brandmessage/groupTag
Try it in the Sandbox

Looks up Brand Message group tag details by sender profile key and group tag key.

Query Parameters

senderKey

RequiredString

The sender profile key.

groupTagKey

RequiredString

The group tag key.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupTag?senderKey={senderKey}&groupTagKey={groupTagKey}" \
2 -H "Authorization: {ApiKey}"

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "groupTags": [{
12 "groupTagKey":"{groupTagKey}",
13 "groupTagName":"VIP ๊ณ ๊ฐ"
14 }]
15 }
16 }
17}

Register a group tag

POST/api/comm/v1/center/brandmessage/groupTag
Try it in the Sandbox

Registers a Brand Message group tag.

Body Parameters

{} JSON

groupTag

RequiredObject

The Brand Message group tag information.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupTag" \
2 -H "Authorization: {ApiKey}" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "groupTag": {
6 "groupTagKey": "VIP_CUSTOMER",
7 "groupTagName": "VIP ๊ณ ๊ฐ"
8 }
9 }'

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "groupTags": [{
12 "groupTagKey":"VIP_CUSTOMER",
13 "groupTagName":"VIP ๊ณ ๊ฐ"
14 }]
15 }
16 }
17}

Update a group tag

PUT/api/comm/v1/center/brandmessage/groupTag
Try it in the Sandbox

Updates a registered Brand Message group tag.

Body Parameters

{} JSON

groupTag

RequiredObject

The Brand Message group tag information.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X PUT "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupTag" \
2 -H "Authorization: {ApiKey}" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "groupTag": {
6 "groupTagKey": "VIP_CUSTOMER",
7 "groupTagName": "VIP ๊ณ ๊ฐ ์ˆ˜์ •"
8 }
9 }'

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "groupTags": [{
12 "groupTagKey":"VIP_CUSTOMER",
13 "groupTagName":"VIP ๊ณ ๊ฐ ์ˆ˜์ •"
14 }]
15 }
16 }
17}

Delete a group tag

DELETE/api/comm/v1/center/brandmessage/groupTag/senderKey/{senderKey}/groupTagKey/{groupTagKey}
Try it in the Sandbox

Deletes a Brand Message group tag by sender profile key and group tag key.

Path Parameters

senderKey

RequiredString

The sender profile key.

groupTagKey

RequiredString

The key of the group tag to delete.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X DELETE "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/groupTag/senderKey/{senderKey}/groupTagKey/{groupTagKey}" \
2 -H "Authorization: {ApiKey}"

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success"
10 }
11}

Manage friend groups

A friend group is a management capability that groups friend audiences by sender profile for use in basic broadcast sends. You can create a group from a file upload or a phone number array, and add or delete phone numbers per group.

Upload a friend group file

POST/api/comm/v1/center/brandmessage/friendGroup/file
Try it in the Sandbox

Uploads a phone number list file and issues a temporary file key for registering a friend group or adding and removing phone numbers.

Body Parameters

FORM-DATA

senderKey

RequiredString

The sender profile key.

file

RequiredBinary

The phone number list file to upload.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/friendGroup/file" \
2 -H "Authorization: {ApiKey}" \
3 -H "Content-Type: multipart/form-data" \
4 -F "senderKey={senderKey}" \
5 -F "file=@friend-group.csv"

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "friendGroup": {
12 "fileKey":"{fileKey}",
13 "expiredAt":"2026-04-10 14:03:25"
14 }
15 }
16 }
17}

Register a friend group

POST/api/comm/v1/center/brandmessage/friendGroup
Try it in the Sandbox

Creates a friend group. You can register the phone numbers to include with fileKey or phoneNumbers.

Body Parameters

{} JSON

friendGroup

RequiredObject

The friend group information.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/friendGroup" \
2 -H "Authorization: {ApiKey}" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "friendGroup": {
6 "senderKey": "{senderKey}",
7 "friendGroupKey": "VIP_CUSTOMERS",
8 "phoneNumbers": [
9 "01000000000",
10 "01000000001"
11 ]
12 }
13 }'

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "friendGroup": {
12 "friendGroupKey":"VIP_CUSTOMERS",
13 "requestId": 1203981,
14 "status":"IN_PROGRESS",
15 "createdAt":"2026-04-09 15:10:00",
16 "modifiedAt":"2026-04-09 15:10:00"
17 }
18 }
19 }
20}

Look up a friend group

GET/api/comm/v1/center/brandmessage/friendGroup
Try it in the Sandbox

Looks up friend group details by sender profile key and friend group key.

Query Parameters

senderKey

RequiredString

The sender profile key.

friendGroupKey

RequiredString

The friend group key.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/friendGroup?senderKey={senderKey}&friendGroupKey=VIP_CUSTOMERS" \
2 -H "Authorization: {ApiKey}"

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "friendGroup": {
12 "friendGroupKey":"VIP_CUSTOMERS",
13 "userCount": 12000,
14 "friendCount": 11540,
15 "status":"COMPLETED",
16 "createdAt":"2026-04-09 15:10:00",
17 "modifiedAt":"2026-04-09 15:12:25"
18 }
19 }
20 }
21}

Look up the friend group list

GET/api/comm/v1/center/brandmessage/friendGroup/list
Try it in the Sandbox

Looks up the friend groups registered for the sender profile.

Query Parameters

senderKey

RequiredString

The sender profile key.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/friendGroup/list?senderKey={senderKey}" \
2 -H "Authorization: {ApiKey}"

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "friendGroups": [{
12 "friendGroupKey":"VIP_CUSTOMERS",
13 "userCount": 12000,
14 "friendCount": 11540,
15 "status":"COMPLETED",
16 "createdAt":"2026-04-09 15:10:00",
17 "modifiedAt":"2026-04-09 15:12:25"
18 }]
19 }
20 }
21}

Delete a friend group

DELETE/api/comm/v1/center/brandmessage/friendGroup/senderKey/{senderKey}/friendGroupKey/{friendGroupKey}
Try it in the Sandbox

Deletes a friend group by sender profile key and friend group key.

Path Parameters

senderKey

RequiredString

The sender profile key.

friendGroupKey

RequiredString

The key of the friend group to delete.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X DELETE "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/friendGroup/senderKey/{senderKey}/friendGroupKey/{friendGroupKey}" \
2 -H "Authorization: {ApiKey}"

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success"
10 }
11}

Add phone numbers to a friend group

POST/api/comm/v1/center/brandmessage/friendGroup/phoneNumber/update
Try it in the Sandbox

Adds phone numbers to an existing friend group. You can supply them with fileKey or phoneNumbers.

Body Parameters

{} JSON

friendGroup

RequiredObject

The friend group information.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/friendGroup/phoneNumber/update" \
2 -H "Authorization: {ApiKey}" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "friendGroup": {
6 "senderKey": "{senderKey}",
7 "friendGroupKey": "VIP_CUSTOMERS",
8 "phoneNumbers": [
9 "01000000002",
10 "01000000003"
11 ]
12 }
13 }'

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "friendGroup": {
12 "friendGroupKey":"VIP_CUSTOMERS",
13 "requestId": 1203982,
14 "status":"IN_PROGRESS",
15 "createdAt":"2026-04-09 15:15:00",
16 "modifiedAt":"2026-04-09 15:15:00"
17 }
18 }
19 }
20}

Delete phone numbers from a friend group

POST/api/comm/v1/center/brandmessage/friendGroup/phoneNumber/delete
Try it in the Sandbox

Removes phone numbers from an existing friend group. You can supply them with fileKey or phoneNumbers.

Body Parameters

{} JSON

friendGroup

RequiredObject

The friend group information.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/friendGroup/phoneNumber/delete" \
2 -H "Authorization: {ApiKey}" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "friendGroup": {
6 "senderKey": "{senderKey}",
7 "friendGroupKey": "VIP_CUSTOMERS",
8 "phoneNumbers": [
9 "01000000003"
10 ]
11 }
12 }'

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "friendGroup": {
12 "friendGroupKey":"VIP_CUSTOMERS",
13 "requestId": 1203983,
14 "status":"IN_PROGRESS",
15 "createdAt":"2026-04-09 15:18:00",
16 "modifiedAt":"2026-04-09 15:18:00"
17 }
18 }
19 }
20}

Upload, by sender profile, the consent evidence required to send promotional Brand Messages. Korean regulations require you to hold this consent evidence.

Upload an evidence file

POST/api/comm/v1/center/brandmessage/marketingAgree
Try it in the Sandbox

Uploads a supporting evidence file that proves consent to receive promotional information. Uploaded files are managed per sender profile, and you can check the registration result with the file key and URL returned in the response.

Body Parameters

FORM-DATA

senderKey

RequiredString

The sender profile key. max: 40

file

RequiredBinary

The supporting evidence file to upload.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/marketingAgree" \
2 -H "Authorization: {ApiKey}" \
3 -F "senderKey={senderKey}" \
4 -F "file=@/path/marketing-agree.pdf"

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success",
10 "data": {
11 "marketingAgree": {
12 "fileKey":"{fileKey}",
13 "fileUrl":"https://mud-kage.kakao.com/.../marketing-agree.pdf"
14 }
15 }
16 }
17}

Manage toll-free opt-out

Manage, by sender profile, the toll-free opt-out information required in Brand Message promotional notices under Korean regulations.

Set the toll-free opt-out information for a sender profile

POST/api/comm/v1/center/brandmessage/unSubscribeContent
Try it in the Sandbox

Registers the toll-free opt-out phone number and verification code for the sender profile. You can use them in the toll-free opt-out notice at the bottom of promotional messages.

Body Parameters

{} JSON

brandmessage

RequiredObject

The toll-free opt-out information.

Returns

common

Object

The common response section.

data

Object

The service response section.

Request example

1curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/brandmessage/unSubscribeContent" \
2 -H "Authorization: {ApiKey}" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "brandmessage": {
6 "senderKey": "{senderKey}",
7 "unsubscribePhoneNumber": "080-1234-1234",
8 "unsubscribeAuthNumber": "12345"
9 }
10 }'

Response example

1{
2 "common": {
3 "authCode":"A000",
4 "authResult":"Success",
5 "infobankTrId":"Infobank-Tracking-Id"
6 },
7 "data": {
8 "code":"A000",
9 "result":"Success"
10 }
11}