SMS fallback when a Kakao Alimtalk fails

SMS fallback when a Kakao Alimtalk fails

Use replaceSms so a text message goes out when the Alimtalk cannot be delivered. Required fields, cost implications, and the mistake that silently sends nothing.

POST /api/v2/notices/send
마크다운 원문 보기

Alimtalk reaches KakaoTalk users only. If someone does not use it, blocked your channel, or delivery fails, the message disappears. For notifications that must arrive — order confirmations, delivery updates — turn on fallback.

What you need

Fallback needs an SMS sending number on top of the Kakao one. Alimtalk alone works with just kakaoSenderKey, but enabling fallback also requires a registered senderKey.

Turning it on

Three fields together. Miss one and the fallback fails silently.

Field Value
replaceSms "Y"
smsSubject Text subject, used when it goes out as LMS
smsContent Text body

Node.js / TypeScript

await sendgo.alimtalk.send({
  templateCode: 'DELIVERY_START_001',
  replaceSms:  'Y',
  smsSubject:  '[Shipment started]',
  smsContent:  'Your order has shipped.\nTracking: #{var2}',
  contacts: [{
    contact: '01012345678',
    var1: 'ORD-001',
    var2: '1234567890',
  }],
});

Python

client.alimtalk.send(
    template_code="DELIVERY_START_001",
    replace_sms="Y",
    sms_subject="[Shipment started]",
    sms_content="Your order has shipped.\nTracking: #{var2}",
    contacts=[{"contact": "01012345678", "var1": "ORD-001", "var2": "1234567890"}],
)

PHP · Laravel

<?php

$sendgo->alimtalk->send([
    'templateCode' => 'DELIVERY_START_001',
    'replaceSms'   => 'Y',
    'smsSubject'   => '[Shipment started]',
    'smsContent'   => "Your order has shipped.\nTracking: #{var2}",
    'contacts'     => [
        ['contact' => '01012345678', 'var1' => 'ORD-001', 'var2' => '1234567890'],
    ],
]);

REST

curl -X POST https://sendgo.io/api/v2/notices/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "templateCode": "DELIVERY_001",
    "scheduleType": "DIRECTLY",
    "replaceSms": "Y",
    "smsSubject": "[Shipment started]",
    "smsContent": "Your order has shipped.\nTracking: #{var2}",
    "kakaoSenderKey": "your_kakao_sender_key",
    "senderKey": "your_sms_sender_key",
    "contacts": [{ "contact": "01012345678", "var1": "ORD-001", "var2": "1234567890" }]
  }'

Variables in the fallback body

Placeholders like #{var1} inside smsContent are substituted per recipient, using the same variables as the Alimtalk template. You do not maintain two separate content sets.

Alimtalk template: [#{var2}] Order #{var1} has shipped.
smsContent:        [#{var2}] Order #{var1} shipped. Tracking #{var3}

Text messages are subject to byte limits, though. Over 90 bytes it goes out as LMS and the price changes.

Common mistakes

  • Omitting smsContent. Setting replaceSms: 'Y' with no body means there is nothing to fall back to, so nothing is sent. The Alimtalk failed and no text arrived — the worst combination, and the single most common incident here.
  • Unregistered SMS sending number. Everything looks fine while you test Alimtalk, then fails the first time a real fallback happens.
  • Unbudgeted cost. Text costs more than Alimtalk. Even a 10% fallback rate moves the bill visibly.
  • Advertising content. Alimtalk is informational so this rarely arises, but when enabling fallback on a Brand Message the text side needs the (광고) prefix and an opt-out notice.

Next

자주 묻는 질문

When does SMS fallback trigger?
When the recipient does not use KakaoTalk, has blocked the channel, or the Alimtalk otherwise fails to deliver. If replaceSms is Y, the text body you supplied goes out instead.
I set replaceSms to Y and nothing was sent at all.
You almost certainly omitted smsContent. With an empty fallback body there is nothing to send, so it fails silently. Supply smsSubject, smsContent and an SMS sending number (senderKey).
How is fallback billed?
You pay for whatever actually went out. A delivered Alimtalk is billed as Alimtalk; a fallback is billed as a text message. Text costs more, so a high fallback rate raises your bill noticeably.
Can the fallback body use template variables?
Yes. Placeholders such as #{var1} inside smsContent are substituted per recipient. Note the body is then subject to SMS/LMS byte limits rather than the Alimtalk template's.

이 문서에서 쓰는 패키지

관련 문서