> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# KakaoTalk production patterns: Alimtalk and Friendtalk

> Structure a production KakaoTalk integration — provision Biz Message credentials with a Kakao reseller, register and structure templates, choose Alimtalk vs Friendtalk, handle the not-a-friend fallback, split bulk vs one-off sends, and track kakao_message_type through delivery webhooks.

# KakaoTalk production patterns: Alimtalk and Friendtalk

This guide walks KakaoTalk (South Korea) end to end: credentials and template registration, choosing between Alimtalk and Friendtalk, the not-a-friend fallback, bulk vs one-off sends, tracking, and payloads that pass or fail validation. The field reference lives on the [KakaoTalk channel page](/channels/kakao); this guide is the ordered playbook for a production integration. The [APAC channels onboarding guide](/guides/asia-channels-onboarding) is the region-wide survey — start here when KakaoTalk is your Korea channel.

## 1. Beta caveat: bring your own Biz Message credentials

KakaoTalk is a **beta** channel. Orbit wires the send and receive paths end to end, but onboarding requires you to provision your own KakaoTalk Biz Message access with a Kakao reseller. The gateway speaks the widely used NHN Cloud Biz Message contract, so the reseller relationship, sender profile registration, and template approvals all happen off-Orbit.

1. Contract with a Kakao Biz Message reseller (NHN Cloud–contract gateway) and register your sender profile (발신프로필). You receive a gateway **app key**, a **secret key**, and a **sender key**.
2. Paste all three values in Orbit under **Settings → Channels → KakaoTalk**. Per-organization credentials take precedence over any platform default and are stored encrypted at rest.
3. Role caveat: until your credentials are connected, every send fails closed with `CHANNEL_NOT_CONFIGURED` (503).

[Tenant-owned controls](/guides/compliance-profiles-assemble) (quiet hours, consent, suppression) apply to Kakao exactly as to SMS — credential ownership is the only extra responsibility this channel adds.

## 2. Template registration walkthrough

Alimtalk is template-only. The approval cycle is off-Orbit, and Orbit never re-checks a template's status — a `template_name` you pass is the code your reseller approved.

1. Draft the template body with `#{variable}` placeholders for each recipient-specific value (name, order id, ETA).
2. Submit it through your reseller's console and wait for Kakao approval. Re-submit after edits — an edited template is a new approval.
3. Reference the approved code as `template_name` (campaign `message_template`) and fill the placeholders with `template_params` (campaign `variables`).

Approved campaign-shaped send:

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns/" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order confirmation — Alimtalk",
    "channel": "kakao",
    "type": "blast",
    "audience_type": "all",
    "message_template": "order_confirmation_kr_v1",
    "variables": { "order_id": "KR-90210", "eta": "2026-06-12" }
  }'
```

Keep the template code in your own registry (a config file or onboarding checklist) — Orbit routes by the code, your reseller approves by the code.

## 3. Choose Alimtalk vs Friendtalk

| Decision question | Alimtalk                                         | Friendtalk                                    |
| ----------------- | ------------------------------------------------ | --------------------------------------------- |
| Reach             | Any phone number, friend or not                  | Only users who added your channel as a friend |
| Content           | Approved template only                           | Free-form `body` + optional image             |
| Send surface      | Campaigns API (`message_template` + `variables`) | Direct `POST /messages/kakao` with a `body`   |
| Typical use       | Order confirmations, OTPs, shipping updates      | Marketing and re-engagement to followers      |

Pick per recipient, not per program. A production integration usually carries both: Alimtalk for transactional traffic, Friendtalk for promotional pushes to followers.

## 4. Fallback when the recipient is not a friend

The gateway rejects a Friendtalk send to a non-follower at the application layer, and Orbit surfaces it as `MESSAGE_SEND_FAILED` (502) with the gateway's result code. Do not drop the send — escalate to Alimtalk:

1. On a `failed` delivery-status event where `metadata.kakao_message_type` is `friendtalk`, re-route the recipient to an approved Alimtalk template with equivalent content ("join the channel as a friend for promos" keeps a working template on file for this escalation).
2. Record the recipient's preference on your own contact model so later promotional pushes skip Friendtalk for that recipient until a follow event proves the relationship.

The follow/unfollow signal comes through the standard inbound webhook envelope — treat `message.received` with `channel: "kakao"` as the update to your friend-relationship cache.

## 5. Bulk vs one-off sends

* **One-off / transactional**: `POST /messages/kakao` (capped at 80 requests/minute per organization) or a small [batch](/guides/messages-batch-sms) job. Use it for OTPs and per-recipient confirmations.
* **Bulk**: the [Campaigns API](/api-reference/endpoints/campaigns). A campaign throttles, retries, and reports per recipient; a loop over the direct endpoint burns the per-organization minute cap and returns `429 RATE_LIMITED`.

The split is not per organization — a transactional program (Alimtalk) and a promotional program (Friendtalk) can each use either surface. What decides it is volume and join semantics, not message type.

## 6. Tracking: kakao\_message\_type and suppression handling

Echo `metadata.kakao_message_type` on every send — it comes back on the delivery-status webhook and tells you which branch of your integration produced the `delivered` / `failed` outcome. Carry your own idempotency/correlation key in the same `metadata` map.

Per-recipient suppression handling: when an Alimtalk or Friendtalk send fails, drop the recipient into your [suppression and opt-out list](/guides/message-suppression) — promotional Friendtalk traffic must honor it before the next campaign launch. The suppression list is a tenant-owned control: your organization owns the entry, Orbit enforces the gate.

## 7. Payloads that pass vs fail VALIDATION\_ERROR

Pass — Friendtalk with a body:

```json theme={null}
{
  "to": "821012345678",
  "body": "Your order has shipped — track it in the Orbit app.",
  "metadata": { "kakao_message_type": "friendtalk" }
}
```

Pass — Alimtalk with an approved template (campaign shape):

```json theme={null}
{
  "channel": "kakao",
  "message_template": "order_confirmation_kr_v1",
  "variables": { "order_id": "KR-90210", "eta": "2026-06-12" }
}
```

Fail — Friendtalk with no body:

```json theme={null}
{
  "to": "821012345678",
  "metadata": { "kakao_message_type": "friendtalk" }
}
```

→ `422 VALIDATION_ERROR` ("KakaoTalk Friendtalk requires a message body").

Fail — Alimtalk with no template (implied when `kakao_message_type` is omitted):

```json theme={null}
{
  "to": "821012345678",
  "body": "Your order has shipped."
}
```

→ `422 VALIDATION_ERROR` ("KakaoTalk Alimtalk is template-only — an approved templateName (templateCode) is required").

## 8. Handover: one template, a pick-list of channels

The same concept serves every template-only Asia channel — KakaoTalk Alimtalk, [WeChat](/channels/wechat), [Zalo](/channels/zalo), and Meta-routed channels. Keep the pick-list pattern: one approved template code, one send shape, only the endpoint path changes. The [template-only playbook](/guides/asia-channels-template-playbook) is the consolidated reference; keep KakaoTalk as the Korea cell in that matrix and reuse the same `template_name` + `template_params` shape you registered in step 2.

## See also

* [KakaoTalk channel page](/channels/kakao) — field reference, error codes, and credential handling.
* [APAC channels onboarding](/guides/asia-channels-onboarding) — LINE, WeChat, Zalo, and the fold-in of KakaoTalk.
* [Template-only Asia channels playbook](/guides/asia-channels-template-playbook) — one approved template across every template channel.
* [Campaigns API](/api-reference/endpoints/campaigns) — bulk sends.
* [Message suppression](/guides/message-suppression) — per-recipient opt-out handling.