Understand messages

This page collects the core concepts worth understanding about messaging before you read the detailed Communication API specifications.

The per-channel specifications (SMS/LMS/MMS/RCS/Biz Message) each have different fields, but in day-to-day operation you integrate more reliably when you also understand the shared concepts: broadcast send, failover (Fallback), variable substitution messages, idempotency keys, and the sender identification code.

The items below focus on the criteria people ask about most often in practice, and are arranged so that you can pick up the context immediately when you meet the same term on a detailed specification page.

Broadcast send (sending multiple messages)

A broadcast send delivers the same message to many recipients at once.

• Split it into request units that match your operational policy.
• Pass the recipient list in the destinations field.
• Recipients are handled separately according to anti-spam policy and each recipient's status.
• A single request can carry up to 200 recipient numbers.
• Avoid firing requests back to back too quickly, and leave a request interval that suits your production environment.
• If you use variable substitution messages, the substitution values are applied per recipient number.
• The acceptance response is also broken out into a result per recipient number.

POST /api/omni
destinations: [{ to: "01000000000" }]
Result: 1 acceptance response

POST /api/omni
destinations: [{ to: "01000000001" }, { to: "01000000002" }, ..., { to: "01000000200" }]
Result: one acceptance response per recipient (up to 200)

Fallback messages (failover)

Fallback is the capability that performs an automatic failover send following the messageFlow order in the send request.

• messageFlow holds the messages in order as an Array.
• If the message earlier in the order fails, it switches automatically to the next message in the order.
• Because the per-channel messages are distinguished inside messageFlow, the send request path stays the same: /api/omni.

{
  "destinations": [{ "to": "01000000000" }],
  "messageFlow": [
    { "alimtalk": { "msgType": "AT", "text": "주문 안내 메시지입니다." } },
    { "sms": { "from": "01000000000", "text": "알림톡 대체 문자입니다." } }
  ]
}

{
  "destinations": [{ "to": "01000000000" }],
  "messageFlow": [
    { "alimtalk": { "msgType": "AT", "text": "안내 메시지입니다." } },
    { "rcs": { "serviceType": "RCS", "msgType": "RS", "content": { "description": "RCS 대체 메시지입니다." } } },
    { "mms": { "from": "01000000000", "subject": "대체 안내", "text": "RCS 실패 시 LMS 대체 발송입니다." } }
  ]
}

Unified RCS and Android RCS

RCS is broadly divided into the unified RCS and Android RCS specifications. Unless you have a specific requirement, we recommend you look first at unified RCS, which supports iOS and Android together.

Kakao request response method (responseMethod)

For Kakao Biz Message, the responseMethod setting changes the criterion used to judge a send request successful.

Push method (recommended)

This method treats the send as successful without checking whether an ACK was received, as long as the active user conditions are met.

• Because you can judge send success quickly, it reduces duplicate message receipt caused by failover sends.
• If the active user conditions are not met, it responds with a NoSendAvailableException error as the result.

Polling method

With this method you make the send request, then confirm separately whether the message actually reached the handset.

• The message sending system treats messages whose receipt result arrives within the timeout as successful (MS03), and treats the rest as success-uncertain (ME09).
• After that, you confirm the send result by requesting the delivery result at regular intervals.
• You can set the timeout on the send request; the range is 10 seconds to 86,400 seconds (1 day). The default is 180 seconds (3 minutes).

International message operational concepts

Because carrier policy differs greatly by country, international message — unlike domestic messages — requires you to review the sender display method, the message signature, and how handset delivery results are collected.

Message signature

When you send messages overseas, some countries require you to insert content that identifies the sender's service name or company name inside the message body, in order to block impersonation of other services and spam messages. This is called a message signature, and it may require pre-registration.

• A well-known example is China, where you must insert a signature of the form 【INFO中国】 at the very front of the text body.
• The signature format can differ by country and carrier, so check whether registration is required and what the insertion rules are before you go live.

Sender ID

The Sender ID is the message sender information — the digits or string shown in the "from" area when the message is received on a handset.

• Some countries and carriers allow string Sender IDs such as Korea as well as numeric ones such as 15882460.
• In some countries you must pre-register a company- or service-specific string with the overseas carrier before you send, in order to block impersonation of other services and spam messages.
• Well-known examples where Sender ID pre-registration matters include Indonesia, India, the Philippines, and Thailand.
• You can get the details from your sales representative; registration typically takes about 2 to 4 weeks.

DLR (delivery report)

DLR means the actual handset delivery result.

• The concept is the same as a domestic report, but for international message the acceptance result from the international aggregator is treated as the standard report. That acceptance result is the basis for billing.
• On request, you can additionally receive the handset delivery result (DLR).
• For 1 message you may collect 1 standard report (acceptance result) and 1 DLR (delivery result) — 2 records in total.

Variable substitution messages

A variable substitution message is one where you specify substitution keywords in the message body or title and send it with the values substituted per recipient.

• Specify substitution keywords in the form #{key} inside the message content (text) or the title (title).
• Enter the substitution values as JSON in replaceWords within the recipient information (destinations).
• The final sentence, with the replaceWords values substituted in, is what reaches the handset.

Message content (text)

안녕하세요 #{name}님,
#{orderName} 주문이 #{status} 상태입니다.

Substitution variables (replaceWords)

{
  "name": "홍길동",
  "orderName": "무선 키보드",
  "status": "배송중"
}

Final handset message

안녕하세요 홍길동님,
무선 키보드 주문이 배송중 상태입니다.

Idempotency key

An idempotency key is an identifying value that prevents duplicate processing of the same request.

• Idempotency key field: idempotencyKey
• Time-to-live field: idempotencyTtl (seconds)
• Re-requesting with the same key reduces duplicate sends even during network retries and timeouts.
• We recommend generating the key from a business unit such as an order number or a verification transaction number.

Originating operator identification code

originCID is the identification code inserted to identify the originating operator when text is sent over the internet; it uses the registration number of a special-category value-added telecommunications operator (9 digits).

• Where it applies: messageFlow[].sms.originCID, messageFlow[].mms.originCID
• Format: length: 9
• If the originating operator is a reseller, the registration number of the first reseller is recorded.
• If the message goes to a text relay operator without passing through a reseller, the text relay operator's registration number is recorded.

Example 1) Company → Reseller 1 → Reseller 2 → Text relay operator → Mobile carrier
Reseller 1's registration number is inserted.

Example 2) Company → Text relay operator → Mobile carrier
The text relay operator's registration number is inserted.

Alimtalk template review

After you register an Alimtalk template it must pass Kakao's review before you can send it. Reviews are processed in order within 2 business days, and a rejected template has to be fixed and resubmitted.

Approval criteria

The template must be an informational message and must also meet the Alimtalk service criteria. An informational message is information you must deliver under a contract or transaction with the recipient; promotional information for commercial purposes does not qualify.

Common rejection reasons

• Promotional wording anywhere in the message
• Variable errors, more than 40 variables, or content made up only of variables
• Coupon issuance notices the recipient did not consent to

Variable constraints

• Every variable needs example text.
• You cannot use more than 40 variables.
• Button names and the preview cannot contain variables.

For the detailed review criteria and image specifications, see the Kakao Alimtalk review guide.