> ## 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

> Send KakaoTalk Biz Messages — Alimtalk templates and Friendtalk — through the Orbit Messaging API

# KakaoTalk

KakaoTalk is Korea's dominant messaging app. Orbit's KakaoTalk channel wraps the KakaoTalk Biz Message gateway so you can reach Korean recipients from the same unified Messaging surface used for every other channel.

<Note>
  KakaoTalk is a **beta** channel. The send and receive paths are wired end to end, but onboarding still requires you to provision your own KakaoTalk Biz Message credentials with a Kakao reseller (the gateway speaks the widely used NHN Cloud Biz Message contract).
</Note>

## Message types

KakaoTalk Biz Message has two distinct message types. Select the type per message with the `kakao_message_type` metadata field (`alimtalk` is the default).

| Type                 | `kakao_message_type` | Audience                                                       | Content                                                                                                                        | Use case                                                                  |
| -------------------- | -------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| **Alimtalk** (알림톡)   | `alimtalk`           | Any phone number, whether or not the user follows your channel | Pre-approved **template** (`template_name` selects the approved template code; `template_params` fills the `#{var}` variables) | Transactional notifications — order confirmations, OTPs, shipping updates |
| **Friendtalk** (친구톡) | `friendtalk`         | Users who have added your channel as a friend                  | Free-form `body` text and an optional image (`media_url`)                                                                      | Marketing and re-engagement to opted-in followers                         |

Alimtalk is template-only: a send without an approved `template_name` is rejected with `VALIDATION_ERROR` (422). Friendtalk requires a non-empty `body`.

## Send a Friendtalk message

Send a single Friendtalk message with `POST /api/v1/messages/kakao` — the direct per-message endpoint, the same shape as every other channel's send route (`/line`, `/telegram`, `/viber`). Set `metadata.kakao_message_type` to `friendtalk`; the free-form message text goes in the top-level `body` field.

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/messages/kakao \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "821012345678",
    "body": "Your order has shipped — track it any time in the Orbit app.",
    "metadata": { "kakao_message_type": "friendtalk" }
  }'
```

### Request body

| Field                         | Type   | Required | Description                                                                                                                              |
| ----------------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `to`                          | string | yes      | Recipient phone number (digits, e.g. `821012345678`).                                                                                    |
| `body`                        | string | yes      | Friendtalk message text.                                                                                                                 |
| `metadata.kakao_message_type` | string | yes      | Must be `friendtalk` for a direct send. When omitted it defaults to `alimtalk`, which this endpoint does not carry (see Alimtalk below). |
| `media_url`                   | string | no       | Friendtalk image URL.                                                                                                                    |
| `metadata`                    | object | no       | Flat map of string→string values. Echoed back on delivery and status webhooks.                                                           |
| `scheduled_at`                | string | no       | RFC 3339 timestamp to defer the send; the message is queued as `scheduled` until then.                                                   |

The sender is selected automatically from the KakaoTalk credentials connected to your organization — you do not pass an app key or sender key on the request.

### Response

`202 Accepted` — the message is queued for delivery; the terminal `delivered` / `failed` state arrives later via the delivery-status webhook.

```json theme={null}
{
  "data": {
    "id": "msg_kakao_abc123",
    "status": "queued",
    "channel": "kakao"
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-06-08T00:00:00Z"
  }
}
```

## Send an Alimtalk message

Alimtalk is template-only — it carries no free-form `body`, so it is sent through the [Campaigns API](/api-reference/endpoints/campaigns) with `channel` set to `kakao`. Select the approved template with `template_name` (the KakaoTalk template code) and fill its `#{var}` placeholders with `template_params`.

| Field                         | Required | Description                                                          |
| ----------------------------- | -------- | -------------------------------------------------------------------- |
| `to`                          | yes      | Recipient phone number (digits).                                     |
| `template_name`               | yes      | The approved KakaoTalk template code.                                |
| `template_params`             | no       | Flat string→string map filling the template's `#{var}` placeholders. |
| `metadata.kakao_message_type` | no       | Leave unset (or `alimtalk`, the default).                            |

The sender is selected automatically from the KakaoTalk credentials connected to your organization — you do not pass an app key or sender key on the request.

## Rate limits

The direct `POST /messages/kakao` endpoint is capped at **80 requests/minute per organization**. Bursts above the cap receive `429` with a `Retry-After` header; back off and retry, or stage high-volume sends through the campaigns API. See [Rate Limits](/guides/rate-limits).

## Configuration

KakaoTalk is a bring-your-own-credential channel. You can connect it per organization in the dashboard, or set platform-default credentials for the whole cluster.

### Per organization (recommended)

1. Provision KakaoTalk Biz Message access with a Kakao reseller and register your sender profile (발신프로필). You receive a gateway **app key**, a **secret key**, and a **sender key**.
2. In the Orbit dashboard, go to **Settings → Channels → KakaoTalk** and paste all three values. Orbit stores them encrypted at rest (`enc:v1:` envelope) under your organization's `settings.channels.kakao` and never echoes them back through any API response.
3. Get your Alimtalk templates approved through your Kakao reseller, then reference each by its template code in `template_name`.

Per-organization credentials take precedence; when an organization has none, sends fall through to the platform default below.

### Platform default

An operator can register a single cluster-wide KakaoTalk provider by setting these environment variables. All three are required — when any is unset the channel stays unregistered and a send fails closed with `CHANNEL_NOT_CONFIGURED`.

| Variable                   | Description                                        |
| -------------------------- | -------------------------------------------------- |
| `DEVOTEL_KAKAO_APP_KEY`    | Biz Message gateway app key.                       |
| `DEVOTEL_KAKAO_SECRET_KEY` | Gateway secret, sent as the `X-Secret-Key` header. |
| `DEVOTEL_KAKAO_SENDER_KEY` | Registered Kakao sender profile key.               |

### Credential handling — your responsibility

The app key, secret key, and sender key are bearer credentials. Anyone holding them can send messages as your KakaoTalk channel. Orbit encrypts them at rest and masks them in the dashboard after submit, but their safety upstream of Orbit (your password manager, CI/CD variables, screenshots) is yours to protect:

* **Never commit a KakaoTalk credential to git**, public or private.
* **Rotate immediately** with your Kakao reseller if you suspect exposure, then re-paste the new values in Orbit.
* **Scope each environment to its own credentials** (dev / staging / production) so a leaked dev secret cannot reach customer conversations.

## Inbound and delivery status

Inbound replies and delivery receipts are normalized by the Orbit messaging gateway and relayed to your account automatically — there is no KakaoTalk webhook for you to register. Replies arrive on the standard `message.received` webhook with `channel: "kakao"`; delivery status advances your outbound message to `delivered` / `failed` as the gateway reports back. Subscribe to these under **Settings → Webhooks**.

## Common errors

| Code                     | HTTP | Cause                                                                                       | Fix                                                                                         |
| ------------------------ | ---- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `INVALID_RECIPIENT`      | 422  | `to` is missing or empty.                                                                   | Supply a recipient phone number.                                                            |
| `VALIDATION_ERROR`       | 422  | Alimtalk sent without an approved `template_name`, or Friendtalk sent without a `body`.     | Provide the field the chosen message type requires.                                         |
| `CHANNEL_NOT_CONFIGURED` | 503  | No KakaoTalk credentials are connected for the organization and no platform default is set. | Connect credentials under **Settings → Channels → KakaoTalk**.                              |
| `MESSAGE_SEND_FAILED`    | 502  | The Biz Message gateway rejected the send (bad template, unfollowed user, gateway error).   | Inspect the gateway result code in the error message and correct the template or recipient. |
| `RATE_LIMITED`           | 429  | More than 80 sends/minute for your organization on `POST /messages/kakao`.                  | Honour the `Retry-After` header; stage bulk sends through the campaigns API.                |

## Pricing

KakaoTalk Biz Message has its own per-message pricing set by Kakao and your reseller. Orbit charges a flat per-1M platform fee for delivery and inbound webhook fan-in. See the [pricing page](https://orbit.devotel.io/pricing).