Channels and SMS fallback

Codes are delivered by KakaoTalk AlimTalk, with an SMS fallback that is on by default and can be turned off per request. Also covers templates and billing.

K-OTP delivers codes by KakaoTalk AlimTalk. When an AlimTalk message cannot be delivered, K-OTP sends the same code by SMS automatically. This SMS fallback is on by default; you can turn it off for a single request with smsFallback: false.

In most integrations you leave channel out of the request. Message bodies come from registered templates; see Channels and templates.

How the channel is chosen

Request	Delivery
`channel` omitted (or `"alimtalk"`)	AlimTalk, with the SMS fallback unless turned off
`channel: "sms"`	Refused with `400 BAD_REQUEST` (`CHANNEL_NOT_SUPPORTED`), nothing is sent

Only a template with an approved KakaoTalk template can be issued. All four templates are approved:

`templateId`	Channels
`otp_default_kr` (default)	AlimTalk (with the SMS fallback)
`otp_login_kr`	AlimTalk (with the SMS fallback)
`otp_signup_kr`	AlimTalk (with the SMS fallback)
`otp_payment_kr`	AlimTalk (with the SMS fallback)

GET /v1/templates returns each template's channelSupport: a template is issuable only when it lists alimtalk. Issuing a template that does not is refused with 400 BAD_REQUEST (TEMPLATE_NOT_AVAILABLE); K-OTP never falls back to a direct SMS. Delivery records and responses still report sms as the delivered channel when the fallback carried the code.

To show your own service name in these messages, see Message templates and service name.

AlimTalk

Sent through an approved KakaoTalk business template. AlimTalk messages arrive in KakaoTalk and are usually read faster than SMS.

SMS fallback (on by default)

When AlimTalk delivery fails (for example the recipient does not use KakaoTalk or the message is rejected), K-OTP automatically sends the same code by SMS. You do not need to call the API again, and the issueId stays the same, so verification works unchanged.

Turning the SMS fallback off (API 1.8.0)

Set smsFallback: false on POST /v1/issue to deliver by AlimTalk only.

`smsFallback`	Effect
omitted or `true`	AlimTalk with the SMS fallback (the default)
`false`	AlimTalk only: no SMS is sent if AlimTalk fails

curl -X POST "https://api.k-otp.dev/v1/issue" \
  -H "Authorization: Bearer $KOTP_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5b0f8f2e-3c1d-4d7a-9a2b-6f1e0c9d8a71" \
  -d '{"phoneNumber":"01012345678","purpose":"login","smsFallback":false}'

Good to know:

With the fallback off, a recipient AlimTalk cannot reach does not get the code. The issue's deliveryStatus shows failed once the provider reports the failure (see Issue lifecycle).
The price does not change: the send costs 1 credit either way (see Billing). With the fallback off, an AlimTalk request the provider refuses is released, one it accepts is debited, and a debited credit is returned if the provider later confirms that delivery failed (see How debits work).
smsFallback is part of the request: send the same value when you retry with the same idempotency key.
The SDKs accept smsFallback from @k-otp/sdk 1.2.0 and from the 0.1.0 server SDKs. With an older @k-otp/sdk, send it through the REST API as shown above.

Billing

Every OTP send costs 1 credit:

AlimTalk: 1 credit, whether AlimTalk delivers the code or the SMS fallback does. The fallback never adds a charge.
AlimTalk with smsFallback: false: 1 credit, the same price.

The credit is reserved when you issue, debited once the messaging provider accepts the send, and released if the provider refuses it. If the provider later confirms that delivery failed, or no delivery result arrives within the tracking window, the debited credit is returned. See How debits work.

Delivery status

GET /v1/status combines verification and delivery into one overallStatus, so your support team can see whether a code was queued, sent, delivered, or verified.