KakaoTalk AlimTalk from your own channel

✅ Verified

Against Axowl.Auth/EndPoints/AppGroupKakaoEndpoints.cs (/api/org/{slug}/app-groups/{groupId}/kakao) and Axowl.Auth/Services/EndUserOtpSender.cs (routing) — 2026-09-06.

What it does

When an app group has a KakaoTalk channel linked and an approved template mapped to the otp purpose, verification codes for Korean phone numbers go out as AlimTalk under your Kakao channel instead of Twilio SMS. Every other case (non-Korean number, no channel, template not approved, insufficient prepaid credit, Popbill error) falls back to SMS, so enabling this never blocks a login.

AlimTalk is metered per message from the organization’s prepaid credit at the list price in the pricing table (pass-through, no markup). A message that Popbill rejects is refunded.

Prerequisites

1. Korean Package add-on on the organization. Everything below returns 402 { error: "ADDON_REQUIRED" } without it.
2. The organization’s Korean business registration number (10 digits). Kakao business channels belong to a registered business, so an organization without one cannot use AlimTalk. Korean organizations enter it when the organization is created; otherwise add it under Billing → Business information.
3. A Kakao business channel, created by you at Kakao Business. Kakao verifies the channel admin by phone, which is why registration is done in Popbill’s own window, not through an API.

Setup (dashboard)

Open the app group → Korean Package tab → Open setup wizard. The wizard walks through the three steps below in one full-screen flow; the only thing you type is the business registration number (and a contact email). Everything else is a Popbill window or a pick from a list.

1. Business verification — enter the 10-digit business registration number. Axowl checks it (National Tax Service status via Popbill) and, where company lookup is enabled, fills in the company name, representative, address and business type; otherwise you type them, with the business address picked from a road-name address search (Ministry of the Interior and Safety API). A business that is not active is flagged. Continuing saves the business profile and registers the organization with Popbill as a linked member.
2. KakaoTalk channel — create your channel at Kakao Business once (guide shown in the step), then register it as a sender in the Popbill window and pick it from the list.
3. Templates — copy the recommended text, register it in the Popbill window, and after Kakao approves it pick it for the otp purpose. You can finish without a template; Korean numbers keep receiving SMS until one is mapped.

The same steps are available individually on the tab itself.

1. Link with Popbill — registers the organization as a linked member under Axowl’s Popbill partner account (once per organization, no cost). Needs the full business profile.
2. Register channel (Popbill) — a Popbill window opens (the URL is valid for 30 seconds). Register your Kakao channel as a sender profile there, then Refresh and pick it.
3. Register sender number (Popbill) — optional. A pre-registered phone number lets Popbill send a plain SMS when a recipient cannot receive AlimTalk.
4. Register template (Popbill) — register the recommended text shown for each purpose. Kakao review takes 2–5 business days. Only approved templates are listed; map the approved one to its purpose and Save.

The otp template must contain the variable #{code}.

API

All routes are under /api/org/{slug}/app-groups/{groupId}/kakao and use the dashboard session (cookie + CSRF), like the other app-group settings.

Method	Path	Scope	Purpose
GET	/	org.app_group.read	Status: business number, Popbill membership, channels, approved templates, sender numbers, current selection, recommended template bodies
POST	/member	org.app_group.update	Join Popbill as a linked member (idempotent)
POST	/popup/{channel|template|sender}	org.app_group.update	Returns { url, expiresInSeconds: 30 } — open it immediately
PUT	/	org.app_group.update	Save { channelId, senderNumber, templateMap }; channelId: null unlinks and clears all three

Business lookup used by the wizard’s first step:

Method	Path	Scope	Purpose
GET	/api/org/{slug}/billing/business-lookup?number=1234567890	view.billing	Checks the number (checksum first, then Popbill business-info lookup) and returns { active, stateLabel, taxTypeLabel, companyName, representativeName, address, businessType, businessItem }. 400 invalid_business_number, 429 rate_limited (30 per organization per day), 502 POPBILL_REJECTED, 503 when lookup is not configured.

Address search used by the same step (Korean road-name address, Ministry of the Interior and Safety API, called server-side so the approval key never reaches the browser):

Method	Path	Scope	Purpose
GET	/api/org/{slug}/billing/address-search?q=테헤란로 152&page=1	view.billing	Returns { total, page, hits: [{ roadAddress, jibunAddress, zipCode, buildingName, siDo, siGunGu, eupMyeonDong }] } (10 per page). 400 keyword_too_short under 2 characters, 429 rate_limited (300 per organization per day), 502 with the upstream error code, 503 when the key is not configured — the wizard then falls back to a plain text field.

PUT re-validates every value against Popbill’s lists: an unknown channel, an unregistered sender number, a template that is not approved, or a template that belongs to another channel is rejected with 400.

Errors you will see:

Status	error	Meaning
402	ADDON_REQUIRED	Korean Package not active
409	BUSINESS_NUMBER_REQUIRED	Organization has no business registration number
409	BUSINESS_INFO_REQUIRED	Business profile incomplete — missing[] lists the fields
409	MEMBER_REQUIRED	Link with Popbill first
502	POPBILL_REJECTED	Popbill refused — code and detail carry Popbill’s reason
503	—	Popbill credentials not configured on this environment

Audit events

appgroup.kakao.channel_linked · appgroup.kakao.channel_changed · appgroup.kakao.channel_unlinked carry the channel id, sender number and template map; appgroup.kakao.member_joined records the Popbill registration. They appear in the organization’s audit timeline like other app-group changes.