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.

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).

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.

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.

{
  "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 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.

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)

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

Getting Started

Channels

AI Agents

Flows

Numbers & Verify

Concepts

Billing

Webhooks

Compliance

Legal

Changelog

KakaoTalk

KakaoTalk

Message types

Send a Friendtalk message

Request body

Response

Send an Alimtalk message

Rate limits

Configuration

Per organization (recommended)

Platform default

Credential handling — your responsibility

Inbound and delivery status

Common errors

Pricing

​KakaoTalk

​Message types

​Send a Friendtalk message

​Request body

​Response

​Send an Alimtalk message

​Rate limits

​Configuration

​Per organization (recommended)

​Platform default

​Credential handling — your responsibility

​Inbound and delivery status

​Common errors

​Pricing

KakaoTalk

Message types

Send a Friendtalk message

Request body

Response

Send an Alimtalk message

Rate limits

Configuration

Per organization (recommended)

Platform default

Credential handling — your responsibility

Inbound and delivery status

Common errors

Pricing