Beware of lookalike sites. The official sites of Korea AI Telecom Inc. are katel.kr, katcloud.kr, zerocall.kr and aicallpay.com.Verify official channels
KAT CloudKOENLog in
Developer docsKAT Cloud API
Contents

KAT Cloud API

With the KAT Cloud API, your server can send and receive text messages on your 070 number, look up call history, transcripts, and summaries, configure AI agents, place AI outbound calls, stream live call audio, and receive webhooks. AI agents use the same features through the KAT MCP server. Create an API key on the API keys page of the console.

Base URL

https://studio-gateway.zerocall.kr

Rate limit

1,200 requests per 60 seconds, per key and per API
ItemValue
Authenticationx-api-key header
Bodyapplication/json, UTF-8 (multipart/form-data for file uploads only)
TimestampsISO 8601 UTC, e.g. 2026-11-16T01:00:00.000Z (Korea time only for credit history dates and outbound calling hours)
Access locationKorean IP addresses only. Non-Korean IPs get 403 GL011

Response format

Successful responses are wrapped in code, message, and result. For readability, the response examples in this documentation show only the value inside result.

json
Response (success)
{
  "code": "0",
  "message": "Success",
  "result": { "id": 789 }
}
Response (failure)
{
  "status": 403,
  "code": "KC008",
  "message": "체험이 끝났거나 이용이 멈춘 KAT Cloud 그룹입니다. 콘솔에서 상태를 확인해 주세요."
}
Response (input validation failure)
{
  "status": 400,
  "code": "GL002",
  "message": "필수 값입니다.",
  "errors": [{ "field": "toPhoneNumber", "reason": "필수 값입니다." }]
}

Use the code in a failure response to identify the cause. The full list is in Error handling. Sending a body field that is not in the table also returns 400 GL002 (field not allowed). Exceptions: POST /mcp and announcement audio file downloads return their content as is, without the wrapper.

Pagination

MethodUsed byRequestResponse
offsetCall history, credit historyoffset, limit{ data, total, offset, limit }
CursorChat rooms, chatscursor, size{ data, nextCursor, hasNext }
CursorAI outbound callscursor, limit{ items, nextCursor } (null at the end)

Pass the cursor exactly as received in the previous response.

Key concepts

Group

The unit that holds your KAT numbers. When you sign up, the console creates one group and a 070 number, and keys created in the console are bound to that group only. groupId in paths and parameters refers to this group.

Number (Channel)

A phone number connected to a group. You make and receive calls and text messages on this number. Its channel ID (channelId) is used to connect an AI agent to the number, to set the caller number for AI outbound calls, and to open a chat room.

AI agent

A voice AI that answers calls (INBOUND) or places them (OUTBOUND). It has instructions, manuals, and tools (your HTTP API or MCP server). An inbound agent connected to a number answers calls to that number.

Media stream

Instead of an AI agent, your server sends and receives call audio directly over WebSocket. Use it to connect your own voice AI to a KAT number.

Chat room · Chat

A chat room is a text conversation between one of your numbers and one customer number; a chat is a single message in it. SMS, LMS, or MMS is chosen by length and images, and the delivery result arrives by webhook.

Call history

The record of one inbound or outbound call. With recording on, the recording file, transcript, and summary are attached.

Quick start

  • Sign up in the console to get a 7-day trial and a 070 number.
  • Create a key on the console API keys page. The full key is shown only once, when you create it.
  • Call GET /group to find your groupId and channelId.
  • Register the events you want to receive (call completed, message received, etc.) with POST /webhook.
  • Send a text message (Chats), create an AI agent and connect it to a number (AI agents), or place a call (AI outbound calls).
bash
export KAT_API_KEY="zpa.123.…"

# 1. Your group and numbers
curl https://studio-gateway.zerocall.kr/group -H "x-api-key: $KAT_API_KEY"

# 2. Webhook to receive when a call ends
curl -X POST https://studio-gateway.zerocall.kr/webhook \
  -H "x-api-key: $KAT_API_KEY" -H "Content-Type: application/json" \
  -d '{ "eventType": "CALL_COMPLETED", "url": "https://my.app/kat/webhook" }'

# 3. Open a chat room with a customer number and send a text message
curl -X POST https://studio-gateway.zerocall.kr/chat-room \
  -H "x-api-key: $KAT_API_KEY" -H "Content-Type: application/json" \
  -d '{ "channelId": 100, "phoneNumber": "01098765432" }'

curl -X POST https://studio-gateway.zerocall.kr/chat \
  -H "x-api-key: $KAT_API_KEY" -H "Content-Type: application/json" \
  -d '{ "chatRoomId": "<result from the response above>", "content": "Your reservation is confirmed." }'

Authentication

Put your API key in the x-api-key header on every request. Create keys on the API keys page in the console. The full key is shown only once, when you create it, so store it somewhere safe (an environment variable or a secret store). Keys have the format zpa.{id}.{64 hex characters}.

http
x-api-key: zpa.123.4f9c…
  • You can set an expiry (1–365 days) when creating a key. If you don't, the key never expires.
  • Keys revoked in the console are rejected immediately.
  • The Authorization header is not read.

Check a key

GET/auth-check

Checks whether the key is valid and which group it is bound to.

json
Response
{
  "apiKeyId": 123,
  "userId": 456,
  "name": "Production server",
  "keyHash": "3f1c…",
  "groupIdList": [789],
  "b2bClientId": null
}

For a key created in the console, groupIdList contains only your one KAT group ID. Keys for a group whose trial has ended or whose service is suspended get 403 KC008 on this API too. To check only the server status without authentication, call GET /.

Auth errors

HTTPcodeWhen
401AU011No x-api-key header
401AU012Invalid format, unknown key, or expired or revoked key (also returned if leading/trailing spaces or line breaks are included)
403PK004The path contains a group ID the key is not bound to
403KC008The group's trial has ended or its service is suspended
403GR076Account suspended under the operating policy
403GL011Called from an IP outside Korea

Scope and permissions

A key created in the console is bound only to your one KAT group. Putting another group ID in the path returns 403 PK004. While the group is on the trial or a paid plan, you can use all of the APIs below.

CategoryAPICondition
Messaging/message/* · /chat-room · /chat—
Call history/call-history · /group/{groupId}/call-history/* · /group/{groupId}/call-record-privacy—
Groups · announcements · usageGET /group · GET|PATCH /group/{groupId} · /group/{groupId}/call-forward · /group/{groupId}/call-announcement · /payment/*—
Adding numbers/group/{groupId}/numbers · /group/{groupId}/numbers/quoteOn a paid plan (otherwise 403 KC101); 30 numbers per group, 3 per group per hour (console included)
Webhooks/webhook—
AI agents/group/{groupId}/agent/* · /group/{groupId}/channelThe group's AI agent feature (KAT groups are created with it on; if it is off, 403 AG002)
AI outbound calls/group/{groupId}/ai-outbound/callsGroups whose outbound calls have not been stopped by the operator (if stopped, 403 AO002)
Media streams/group/{groupId}/media-stream/*The group's media stream feature (KAT groups are created with it on)
MCPPOST /mcpSame conditions as above, per tool
Not availablePOST /group · DELETE /group/{groupId} · member APIsCreating or deleting groups: 403 KC006 (add numbers with the Adding numbers API); members: 403 KC007

Trial and suspension

A 7-day trial starts when you sign up. The trial includes 70 minutes of outbound calls, 500 minutes of inbound calls, and 50 messages, and ends after 7 days or when the included usage runs out. During the trial, once the included messages are used up, sending messages returns 403 KC012; when less than 1 minute of included outbound time remains, AI outbound calls and outbound streams return 403 AO016. Check what remains with Included usage · usage.

For a group whose trial has ended or whose service is suspended, every API returns 403 KC008. Sending messages is blocked too. Check the status on the Billing page in the console. If you register a card after the trial ends, you start on the Personal plan; if service was suspended for nonpayment, it resumes as soon as you top up credits.

Rate limits

Rate limits are counted separately for each API (endpoint). With the same key, you can call GET /call-history and POST /chat up to 1,200 times per minute each. Requests that differ only in the IDs in the path (/group/1/agent, /group/2/agent) count as the same API.

Counted byLimitWindow
API key1,200 requests60 seconds
Requesting IP (including requests with a missing or invalid key)3,600 requests60 seconds
  • The window is a fixed 60 seconds. Once you exceed the limit within a window, you are blocked for 60 seconds from that point.
  • Rate limits are counted before authentication. Requests sent with an invalid key also count toward the limit.
  • For MCP, every tool call counts toward the single POST /mcp API.
json
Response (429 Too Many Requests)
Retry-After: 37

{
  "status": 429,
  "code": "G429",
  // Server message in Korean: "Too many requests. Please try again later."
  "message": "요청이 너무 많습니다. 잠시 후 다시 시도해 주세요."
}

When you get a 429, wait for Retry-After (seconds) before retrying. The X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset(seconds remaining) response headers reflect the IP limit, so don't use them to estimate the key limit.

Among 429 responses, G429 is the rate limit, while AO013 (too many concurrent outbound calls) and AO014 (daily outbound call count exceeded) are business limits. Business limits may not clear just by waiting, so handle them separately by code.

Groups

A group is the unit that holds your 070 numbers. When you sign up for KAT Cloud, the console creates a group and a number for you, and keys created in the console are bound to that one group. Use the id you get here as the groupId in the AI agent, call history, AI outbound call, and media stream APIs.

MethodPathDescription
GET/groupList groups
GET/group/{groupId}Get group details
PATCH/group/{groupId}Change name, call recording, messaging tool
GET/group/{groupId}/call-forwardGet call forwarding number
PATCH/group/{groupId}/call-forwardChange call forwarding number

List groups

GET/group

Returns the groups bound to the key as an array. A key created in the console returns your one KAT group.

json
Response
[
  {
    "id": 789,
    "title": "07012345678",
    "phoneNumber": "07012345678",
    "channelId": 100,
    "status": "ACTIVE",
    "createdAt": "2026-11-02T09:00:00.000Z",
    "recordingEnabled": false
  }
]
FieldTypeDescription
idnumberGroup ID
titlestringGroup name (initially the 070 number)
phoneNumberstringThe group's 070 number
channelIdnumberID of that number
statusstringACTIVE = in service. Groups whose trial has ended or whose service is suspended get 403 KC008 on this API too, so responses normally contain only ACTIVE
createdAtstringCreation time (ISO 8601)
recordingEnabledbooleanWhether calls are recorded. Off initially

If a group has several numbers, this list shows only one of them. To see all numbers in a group, use GET /group/{groupId}/channel in Connect numbers.

Get group details

GET/group/{groupId}

Returns the settings of one group. The fields used by KAT Cloud are listed in the table below.

json
Response
{
  "id": 789,
  "title": "07012345678",
  "phoneNumber": "07012345678",
  "status": "ACTIVE",
  "recordingEnabled": false,
  "useSMSTool": false,
  "memberList": [
    {
      "id": 1201,
      "isOwner": true,
      "name": "Gildong Hong",
      "phoneNumber": "01012345678",
      "isPending": false,
      "isCallReceiveEnabled": false
    }
  ],
  "createdAt": "2026-11-02T09:00:00.000Z"
  // … other fields are not used by KAT Cloud
}
FieldTypeDescription
idnumberGroup ID
titlestringGroup name
phoneNumberstringMain number
statusstringSame as in List groups
recordingEnabledbooleanWhether calls are recorded
useSMSToolbooleanWhether the AI agent's send-message tool is enabled
memberListobject[]A KAT group contains only the one account that signed up
createdAtstringCreation time (ISO 8601)

The response also includes other fields, such as plan, answering mode, and staff handoff, but they have no effect on KAT Cloud call behavior, so don't use them. To check the call forwarding number, use Get call forwarding number.

Errors: another group's ID returns 403 PK004; a group that doesn't exist returns 404 GR001.

Update group settings

PATCH/group/{groupId}

Only the fields you send are changed. KAT Cloud uses the three fields below.

FieldTypeRequiredDescription
titlestringNoGroup name. 80 characters or fewer
recordingEnabledbooleanNoTurn call recording on or off. Same setting as Call recording on the console Numbers page
useSMSToolbooleanNoLets the AI agent send a text message to the other party's number during a call. Sent messages are charged messaging fees, and during the trial they are deducted from the included messages
json
Request
PATCH /group/789

{ "recordingEnabled": true }
Response
{ "id": 789 }

Call recording

  • Once turned on, recording starts with the next call. Recorded calls get a transcript and a summary, which appear in call history and in the CALL_COMPLETED webhook.
  • Transcripts, summaries, and recording storage are charged. For transcripts and summaries, call audio is sent to an AI provider outside Korea.
  • Let callers know the call is recorded. For AI agent calls, say so in the agent's greeting; for SIP trunk and media stream calls, use the call-start announcement.
This API also accepts other fields (routeToAi, handoffEnabled, handoffDisabledMessage, useCRMTool), but they don't fit KAT Cloud call flows, so don't send them. Whether the AI agent transfers a call to a person follows the call forwarding number setting.

Errors: 400 GL002 (validation failed or unknown field), 403 PK004, 404 GR001.

Call forwarding number

The number the AI agent transfers a call to when the caller asks for a person. Calls to a number with no AI agent connected also go to this number. Same value as "Call forwarding number" on the console Numbers page.

  • If a forwarded call isn't answered within 60 seconds, the call is ended.
  • The forwarded leg is billed as an outbound call.
  • A CALL_RECEIVED webhook is sent when the call is forwarded. The reason the agent gave for the transfer is in handOffReason.

Get

GET/group/{groupId}/call-forward
json
Response
{
  "isCallForwardEnabled": true,
  "callForwardNumber": "01012345678"
}
FieldTypeDescription
isCallForwardEnabledbooleanWhether call forwarding is on
callForwardNumberstring | nullSaved call forwarding number. The last number is kept even when forwarding is off

Change

PATCH/group/{groupId}/call-forward
FieldTypeRequiredDescription
isCallForwardEnabledbooleanYestrue to keep forwarding on
callForwardNumberstringNoCall forwarding number. Hyphens are removed before saving. If omitted, the saved number is used; if there is none, the mobile number you signed up with
json
Request
PATCH /group/789/call-forward

{ "isCallForwardEnabled": true, "callForwardNumber": "010-2345-6789" }
Response
null

Only mobile numbers (010, 011, 016–019), area-code numbers (02, 031–064), and 070 numbers can be used as the call forwarding number. Other numbers (060, 080, representative numbers, international numbers, etc.) return 400 KC013. Don't use your own KAT number as the call forwarding number.

Turn call forwarding on and off on the console Numbers page. Use this API to change an already-enabled call forwarding number to a different number (send it with isCallForwardEnabled: true). After changing it, check the value with the Get API.
ErrorMeaning
400 GL002Invalid number format (digits only, must be 8–12 digits starting with 0)
400 KC013Not a mobile, area-code, or 070 number
400 GR007Turning forwarding on, but there is no number to use
403 PK004 · 404 GR001Another group's ID · group doesn't exist

Add numbers

Adds one more 070 number to the group at a time. The number joins the same group as the number you got at sign-up; no new group is created. The issue_number tool in MCPand "Add number" on the console Numbers page do the same thing and share the limits below.

  • Available only while you are on a paid plan. During the trial, or when payment is overdue or service is suspended, it returns 403 KC101.
  • By adding them yourself, a group can have up to 30 numbers (409 KC102). Each group can add up to 3 numbers per hour (429 KC103; console, API and MCP combined). If you need more, contact KAT Cloud.
  • Number fees are charged with the monthly fee starting from the next billing period (not prorated). At list prices, the first number is free and the 2nd–30th numbers cost KRW 1,800 per month each (excluding VAT); if you have a contract rate, that rate applies.
  • A new number receives calls only after you connect an AI agent to it with Connect numbers.
  • There is no API to release (return) a number. Contact KAT Cloud.

Preview the added monthly fee

GET/group/{groupId}/numbers/quote

Doesn't add a number. Shows only how much the monthly fee would increase with one more number, and what would block it right now.

json
Response
{
  "groupId": 789,
  "numbers": 1,
  "addedMonthlyFee": 1800,
  "currency": "KRW",
  "blockedCode": null
}
FieldTypeDescription
numbersnumberNumber of numbers currently in the group
addedMonthlyFeenumberMonthly fee increase for one more number (KRW, excluding VAT)
blockedCodestring | nullError code an add request would be rejected with right now (KC101, KC102, KC103, CH008, etc.). null if none

Add a number

POST/group/{groupId}/numbers

You must send the Idempotency-Keyheader. Resending with the same key returns the number issued the first time (for 7 days) instead of issuing a new one, so you can safely retry if you didn't get a response. Sending a different group with the same key returns 409.

HeaderRequiredDescription
Idempotency-KeyYesYour key identifying one add-number request, 1–128 characters
FieldTypeRequiredDescription
confirmMonthlyFeebooleanYestrue once you have confirmed the added monthly fee. Any other value returns 400
json
Request
POST /group/789/numbers
Idempotency-Key: number-20261116-0001

{ "confirmMonthlyFee": true }
Response 201
{
  "groupId": 789,
  "channelId": 412,
  "phoneNumber": "07012345678",
  "addedMonthlyFee": 1800,
  "currency": "KRW",
  // notice is a fixed server message in Korean: "The new number receives calls only after you
  // connect an AI agent to it. The number fee is charged with the monthly fee from the next
  // billing period (not prorated)."
  "notice": "새 번호에 AI 상담원을 연결해야 그 번호로 온 전화를 받습니다. 번호 요금은 다음 결제 기간부터 월 요금과 함께 빠집니다(일할 없음)."
}
ErrorMeaning
403 KC101Not currently on a paid plan (trial, overdue payment, or suspended)
409 KC102The group already has 30 numbers
429 KC103This API key has already added 3 numbers within the last hour
429 CH008Exceeds the line limit per subscriber
406 CH003No number available right now. Try again later or contact us
409Different content with the same Idempotency-Key, or an add-number request for the same group is already in progress

Done in the console

Number and account tasks are done in the console. To get more numbers, use the Add numbers API. The APIs that create or delete groups (POST /group, DELETE /group/{groupId}) are rejected with 403 KC006, and the APIs that add or remove members (/group/{groupId}/member) with 403 KC007. KAT groups have no members; staff handoff is done through the call forwarding number.

TaskConsole page
Get a 070 numberYou get one right after signing up. If the number is still pending, Home shows a notice. To get more, use Numbers › Add number or the Add numbers API
Turn call forwarding on/offNumbers › Call forwarding number
Turn call recording on/offNumbers › Call recording (also available via the API)
Connect your own SIP server (PBX, LiveKit, etc.)SIP trunk
Create and revoke API keysAPI keys
Cards, credits, plansBilling
Cancel KATAccount › Cancel KAT

Check usage and remaining trial included usage with Included usage · usage.

Call-start announcement

This announcement is not played on AI agent calls.It plays only on SIP trunk calls and media stream calls. To tell callers on AI agent calls that they are talking to AI or being recorded, put it in the agent's greeting (AI agents).

Plays a short announcement (up to 20 seconds) when a call connects. Inbound calls (inbound) and outbound calls (outbound) are configured separately. Both directions are off initially.

CallWhen · to whom
SIP trunk · inboundTo the caller, before a call to your 070 number is passed to your SIP server (SIP trunk)
SIP trunk · outboundTo the person who answered, right after they answer a call your SIP server placed through KAT Cloud
Media stream · inboundTo the caller, after KAT Cloud answers the call (Inbound stream)
Media stream · outboundTo the person who answered, after they answer, at the same time as the connection to your WebSocket server (Outbound stream)

On media stream calls, call audio is not sent to your server until the announcement ends (up to 25 seconds). The start message arrives after the announcement ends. On outbound streams, there can be a gap as long as the announcement between connected and start.

MethodPathDescription
GET/group/{groupId}/call-announcementGet settings
PUT/group/{groupId}/call-announcementUpdate settings
PUT/group/{groupId}/call-announcement/audioUpload an audio file (multipart)
DELETE/group/{groupId}/call-announcement/audioDelete the uploaded audio file
GET/group/{groupId}/call-announcement/audioDownload the playback audio (WAV)

Announcement types (messageType)

ValueWhat is played
AI_NOTICE이 통화는 인공지능 상담원이 응대합니다. ("This call is handled by an AI agent.")
RECORDING_NOTICE이 통화는 서비스 품질 향상을 위해 녹음될 수 있습니다. ("This call may be recorded to improve service quality.")
AI_AND_RECORDING이 통화는 인공지능 상담원이 응대하며, 서비스 품질 향상을 위해 녹음될 수 있습니다. ("This call is handled by an AI agent and may be recorded to improve service quality.") (default)
CUSTOM_TEXTReads the text in customText aloud
CUSTOM_AUDIOPlays the audio file uploaded for that direction
Changes take effect from the next call, within 5 minutes at most. Check audioReady in the response to see whether the playback audio has been generated.

Get settings

GET/group/{groupId}/call-announcement

Per-direction settings are in inbound and outbound. Both have the same shape.

json
Response
{
  "inbound": {
    "enabled": true,
    "messageType": "AI_AND_RECORDING",
    "customText": null,
    "spokenText": "이 통화는 인공지능 상담원이 응대하며, 서비스 품질 향상을 위해 녹음될 수 있습니다.",
    "hasCustomAudio": false,
    "customAudioDurationMs": null,
    "audioReady": true,
    "audioUpdatedAt": "2026-11-16T01:00:00.000Z"
  },
  "outbound": {
    "enabled": false,
    "messageType": "AI_AND_RECORDING",
    "customText": null,
    "spokenText": "이 통화는 인공지능 상담원이 응대하며, 서비스 품질 향상을 위해 녹음될 수 있습니다.",
    "hasCustomAudio": false,
    "customAudioDurationMs": null,
    "audioReady": false,
    "audioUpdatedAt": null
  },
  "direction": "INBOUND",
  "enabled": true,
  "messageType": "AI_AND_RECORDING",
  "customText": null,
  "spokenText": "이 통화는 인공지능 상담원이 응대하며, 서비스 품질 향상을 위해 녹음될 수 있습니다.",
  "hasCustomAudio": false,
  "customAudioDurationMs": null,
  "audioReady": true,
  "audioUpdatedAt": "2026-11-16T01:00:00.000Z"
}
FieldTypeDescription
enabledbooleanWhether the announcement plays in this direction
messageTypestringAnnouncement type
customTextstring | nullSaved custom text
spokenTextstring | nullText that is (or will be) played. null when an uploaded audio file is used
hasCustomAudiobooleanWhether an audio file has been uploaded for this direction
customAudioDurationMsnumber | nullLength of the uploaded audio file (milliseconds)
audioReadybooleanWhether playback audio for the current type has been generated
audioUpdatedAtstring | nullWhen the playback audio was last generated (ISO 8601)

The top-level direction, enabled, messageType, and similar fields are kept for compatibility with the legacy format. If only one direction is on, they hold that direction's values (direction is INBOUND or OUTBOUND); if both are on or both are off, they hold the inbound values with direction: "BOTH". New integrations should read inbound and outbound.

Update settings

PUT/group/{groupId}/call-announcement

Send only the fields to change, per direction, in inbound and outbound. Omitted directions and omitted fields keep their saved values. The response has the same shape as Get settings.

FieldTypeRequiredDescription
inboundobjectNoInbound call settings
outboundobjectNoOutbound call settings
inbound.enabled · outbound.enabledbooleanNoTurn the announcement on or off
inbound.messageType · outbound.messageTypestringNoAnnouncement type
inbound.customText · outbound.customTextstringNoText to read for CUSTOM_TEXT. 200 characters or fewer; leading and trailing whitespace is trimmed
json
Request
PUT /group/789/call-announcement

{
  "inbound": { "enabled": true, "messageType": "AI_AND_RECORDING" },
  "outbound": {
    "enabled": true,
    "messageType": "CUSTOM_TEXT",
    "customText": "Hello, this is a call to confirm your reservation. This call is recorded."
  }
}
  • Choosing CUSTOM_TEXT with empty text returns 400 KC033; choosing CUSTOM_AUDIO with no file uploaded for that direction returns 400 KC032. Upload the file first in Audio file.
  • If the spoken text runs longer than 20 seconds, you get 400 KC034; if the audio can't be generated or saved, 502 KC035. In these cases that direction's settings are not changed.
If you send both directions at once, inbound is saved first, then outbound. If outbound fails with KC034 or KC035, inbound may already have changed. When you get an error, check the current values with Get settings, then resend only the direction that failed.

Legacy format (for compatibility)

The format that sends enabled, direction, messageType (all three required) and customText (optional) at the top level is also accepted. If direction is BOTH, the same content is saved for both directions; if it is INBOUND or OUTBOUND, it is saved for that direction and the other direction is turned off. New integrations should use the per-direction format.

Mixing the two formats, sending nothing to change, or omitting one of the three fields in the legacy format returns 400 KC037.

Audio file

Upload

PUT/group/{groupId}/call-announcement/audio

Send the audio file in the file field of multipart/form-data. Use the direction query (INBOUND, OUTBOUND, BOTH) to choose which direction it is for; if omitted, it is used for both. Uploading changes that direction's messageType to CUSTOM_AUDIO. On/off (enabled) is unchanged, so if it was off, turn it on with Update settings for it to play.

  • Format: WAV (16-bit PCM or μ-law, 8–48 kHz) or MP3 (8–48 kHz). Detected from the file contents, not the extension.
  • Up to 5 MB and 20 seconds long.
  • Uploaded files are converted to telephone quality (8 kHz mono) before saving.
bash
curl -X PUT "https://studio-gateway.zerocall.kr/group/789/call-announcement/audio?direction=INBOUND" \
  -H "x-api-key: $KAT_API_KEY" \
  -F "file=@notice.wav"

The response has the same shape as Get settings.

Delete

DELETE/group/{groupId}/call-announcement/audio

Deletes the uploaded file for the direction query (INBOUND, OUTBOUND, BOTH; both directions if omitted). If that direction was using the uploaded file, it reverts to the default announcement (AI_AND_RECORDING). Directions with no file are skipped. The response has the same shape as Get settings.

Download (preview)

GET/group/{groupId}/call-announcement/audio

Returns the audio currently being played as a WAV file (8 kHz 16-bit mono). Unlike other APIs, this one is not wrapped in { code, message, result }; it sends the file as-is (Content-Type: audio/wav). The direction query is either INBOUND or OUTBOUND; if omitted, it is the same direction as the top-level fields in Get settings. If no audio has been generated yet, it returns 404 KC036 (JSON error).

bash
curl -o announcement.wav \
  -H "x-api-key: $KAT_API_KEY" \
  "https://studio-gateway.zerocall.kr/group/789/call-announcement/audio?direction=OUTBOUND"

Errors

CodeHTTPMeaning
KC030403Not a KAT Cloud group
KC031400Audio file can't be uploaded (format, sample rate, over 5 MB). The reason is in message
KC032400CUSTOM_AUDIO chosen but no file uploaded, or the upload request has no file
KC033400CUSTOM_TEXT chosen but the text is empty
KC034400Announcement longer than 20 seconds (both uploaded files and spoken text)
KC035502Couldn't generate or save the announcement audio. Try again later
KC036404No playback audio generated yet (download)
KC037400Nothing to change, per-direction and legacy formats mixed, or a required field missing in the legacy format
G413413Uploaded file is too large
PK004 · GR001403 · 404Another group's ID · group doesn't exist

Chat rooms

A chat room is the message conversation between one of your numbers (channels) and one customer number. Messages the customer sends, messages sent with the chat API, and messages sent with the message sending API all collect in this room.

MethodPathDescription
GET/chat-roomList chat rooms
GET/chat-room/{chatRoomId}Get a chat room
POST/chat-roomOpen a chat room (returns the existing room if there is one)
DELETE/chat-room/{chatRoomId}Leave a chat room

List chat rooms

GET/chat-room

Pages with a cursor, starting from the room with the most recent last message. Rooms you left are not returned. For the next page, pass the nextCursor you received as cursor unchanged. When there are no more pages, hasNext is false.

FieldTypeRequiredDescription
groupIdnumberYesYour group ID. 403 PK004 if outside the key's scope
phoneNumberstringNoSearch by customer number (partial matches work)
keywordstringNoSearch message content in the room. Matching messages are attached in matchedChatList
cursorstringNonextCursor from the previous response. 400 CR002 if malformed
sizenumberNo1–200, default 50
json
Request
GET /chat-room?groupId=789&keyword=reservation&size=20
Response
{
  "data": [
    {
      "id": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
      "groupId": 789,
      "channelId": 100,
      "channelType": "PHONE",
      "channelPhoneNumber": "07012345678",
      "guestPhoneNumber": "01098765432",
      "contactId": 123,
      "contactTitle": "John Doe",
      "lastMessageContent": "Can I change my reservation time for tomorrow?",
      "lastMessageAt": "2026-11-16T01:30:00.000Z",
      "sequence": 15,
      "operatorReadSequence": 15,
      "guestReadSequence": 14,
      "isChannelRemoved": false,
      "matchedChatList": [
        {
          "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "content": "Can I change my reservation time for tomorrow?",
          "timestamp": "2026-11-16T01:30:00.000Z",
          "cursor": "eyJjcmVhdGVkQXQiOi..."
        }
      ]
    }
  ],
  "nextCursor": "eyJsYXN0TWVzc2FnZUF0Ijo...",
  "hasNext": true
}

Response fields

FieldTypeDescription
idstringChat room ID
groupId · channelIdnumberGroup ID and channel (your number) ID
channelTypestringChannel type. PHONE for KAT numbers
channelPhoneNumberstringYour number
guestPhoneNumberstringCustomer number
guestNamestringOnly when the customer's name is known (otherwise the field is omitted)
contactId · contactTitlenumber · stringOnly when the number is in the group's contacts
lastMessageContent · lastMessageAtstringLast message and its time. Messages sent through the API do not change these values
sequencenumberLast sequence number of messages in the room
operatorReadSequence · guestReadSequencenumberRead position of the operator and the customer
isChannelRemovedbooleanWhether your number was removed. If true, you cannot send to this room
matchedChatListobject[]Only when keyword is given. Pass an item's cursor as the cursor of GET /chat to see the messages around it
Messages sent through the API do not change the room's last message, so rooms where you only sent messages through the API are hard to find by list order. Store the chat room ID from the POST /chat-room or POST /chat response and check it with Get a chat room or List messages. To find a room by customer number, use phoneNumber.

Get a chat room

GET/chat-room/{chatRoomId}

Returns the same shape as a list item (without matchedChatList). A room that does not exist or that you left returns 404 CR001; a room in another group returns 403 PK004.

Open a chat room

POST/chat-room

Opens a room for your number and a customer number. If a room for the same number pair already exists, no new room is created and that room's ID is returned. The response is the chat room ID as a string (201).

FieldTypeRequiredDescription
channelIdnumberYesYour number (channel) ID. Find it with GET /group
phoneNumberstringYesCustomer number. Hyphens are removed before reading; must be 8–12 digits starting with 0
json
Request
POST /chat-room

{
  "channelId": 100,
  "phoneNumber": "010-9876-5432"
}
Response
"yyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
HTTPCodeWhen
400GL002Invalid number format ("올바른 전화번호 형식이 아닙니다." — "Not a valid phone number format.")
404CH001Channel does not exist or was removed
403PK004Channel belongs to another group

Leave a chat room

DELETE/chat-room/{chatRoomId}

Deletes the room. The response is the deleted chat room ID as a string. After deletion the room drops out of the list, and getting it or sending to it returns 404 CR001.

If you call POST /chat-room with the same number and customer number after deleting, a new roomis created and you get a new ID. The deleted room's conversation is not moved to the new room. Sending a message to that number also lands in the new room. Replace any stored chat room ID with the new one.

Chat

Read messages in a chat room and send messages to a chat room.

List messages

GET/chat

Returns the newest messages first. The cursor works in both directions: nextCursor moves to older messages and prevCursor to newer ones. Pass the cursor you received as cursor unchanged.

FieldTypeRequiredDescription
chatRoomIdstringYesChat room ID. 404 CR001 if the room does not exist
cursorstringNonextCursor or prevCursor from the previous response, or matchedChatList[].cursor from the chat room search. 400 CH005 if malformed
cursorDatestringNoStart from messages before this time (ISO 8601). Ignored when cursor is given
sizenumberNo1–200, default 50
json
Request
GET /chat?chatRoomId=yyyyyyyyyyyyyyyyyyyyyyyyyyyyyy&size=50
Response
{
  "data": [
    {
      "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "chatRoomId": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
      "channelId": 100,
      "groupId": 789,
      "sequence": 15,
      "content": "Your reservation has been changed to 3 PM.",
      "imageList": [],
      "senderType": "OPERATOR",
      "sendStatus": "SUCCESS",
      "resultStatus": "4100",
      "chatType": "SMS",
      "timestamp": "2026-11-16T01:31:00.000Z"
    },
    {
      "id": "zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz",
      "chatRoomId": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
      "channelId": 100,
      "groupId": 789,
      "sequence": 14,
      "content": "Can I change my reservation time for tomorrow?",
      "imageList": [],
      "senderType": "GUEST",
      "timestamp": "2026-11-16T01:30:00.000Z"
    }
  ],
  "nextCursor": "eyJjcmVhdGVkQXQiOi...",
  "hasNext": true,
  "prevCursor": null,
  "hasPrev": false
}

Response fields

Fields with no value are omitted from the response (for example, messages from the customer have no sendStatus or chatType).

FieldTypeDescription
idstringMessage ID (chatId)
chatRoomId · channelId · groupIdstring · numberChat room, channel, and group the message belongs to
sequencenumberSequence number within the room
contentstringBody
subjectstringSubject (only when present)
imageListstring[]Image URLs. Temporary URLs generated when the response is built
senderTypestringOPERATOR (operator or API send) · GUEST (customer) · AI (AI agent) · HQ (headquarters notice)
senderUserIdnumberOnly for messages sent by an operator. Absent on messages sent through the API
sendStatusstringSend request result for outgoing messages. SUCCESS · FAILED · CANCELED (an operator canceled a failed message)
resultStatusstringCarrier result code. Filled in after the result arrives (result codes)
chatTypestringSMS · LMS · MMS · RCS · KAO (KakaoTalk) · WEB
timestampstringCreation time (ISO 8601)
sendStatus: SUCCESSmeans the message was handed to the carrier. Whether it reached the customer's phone is determined by resultStatus. The success codes are 4100 (SMS), 6600 (LMS · MMS), and 7000 (KakaoTalk).

Send to a chat room

POST/chat

Sends a message to the customer in the chat room. The message is sent as soon as the request arrives, and the result is returned as sendStatus (SUCCESS or FAILED) (201). The carrier result arrives later through the SEND_RESULT webhook or Get send result.

FieldTypeRequiredDescription
chatRoomIdstringYesChat room ID to send to
contentstringYesBody
subjectstringNoSubject. If set, the message goes as LMS or higher. 400 CH004 if over 64 bytes in EUC-KR (32 Korean characters)
imageListstring[]NoList of image keys. Use the values from the media upload response (300 characters or less each, no commas)
externalMessageIdstringNoYour own message ID. It is only stored and returned; sending again with the same value sends again (no deduplication)

Message type

TypeCondition
MMSimageList contains at least one image
SMSNo subject, and the body is 90 bytes or less in EUC-KR (Korean characters 2 bytes, English letters and digits 1 byte)
LMSEverything else (has a subject, or the body is over 90 bytes)

Characters outside the Korean messaging standard (EUC-KR), such as emoji, may be removed from the body and subject, or the message may be sent as LMS. The body actually sent is the content in the response.

json
Request
POST /chat

{
  "chatRoomId": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
  "content": "Your reservation has been changed to 3 PM.",
  "externalMessageId": "ext-msg-001"
}
Response
{
  "chatId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "chatRoomId": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
  "groupId": 789,
  "channelId": 100,
  "content": "Your reservation has been changed to 3 PM.",
  "imageList": [],
  "externalMessageId": "ext-msg-001",
  "sendPhoneNumber": "07012345678",
  "recvPhoneNumber": "01098765432",
  "sendStatus": "SUCCESS",
  "chatType": "SMS",
  "createdAt": "2026-11-16T01:31:00.000Z"
}

Response fields

FieldTypeDescription
chatIdstringMessage ID. Matches data.chatId in the SEND_RESULT webhook and the path value of Get send result
chatRoomId · groupId · channelIdstring · numberChat room, group, and channel the message was sent from
content · subjectstringBody and subject actually sent
imageListstring[]Image keys from the request (not URLs)
externalMessageIdstringValue from the request
sendPhoneNumber · recvPhoneNumberstringSender number · recipient number
sendStatusstringSUCCESS (handed to the carrier) · FAILED (could not be handed over)
chatTypestringSMS · LMS · MMS
resultStatus · resultMessagestringCarrier result. Usually empty right after sending, so the fields are omitted
createdAtstringCreation time

FAILED comes back as a normal response (201), not an error. The message is stored and also appears in List messages. To retry, call POST /chat again.

Errors

HTTPCodeWhen
400GL002Invalid body (including missing fields and fields not in the table)
400CH004Subject is over 64 bytes
400CH007Contains a blocked word or link
402CB001Insufficient credit balance, or auto top-up failed
402GR016The group's message sending is blocked due to insufficient balance
403GR076Group suspended under the operating policy
403PK004Chat room belongs to another group
404CR001Chat room does not exist or was left, or your number (channel) was removed so you cannot send

Upload media

POST/chat/media/upload

Upload images for MMS first. Put up to 3 files at a time, up to 10MB each, in the files field of multipart/form-data. Pass the keys from the response unchanged into imageList of POST /chat.

  • Images only: jpg · jpeg · png · gif · webp · bmp. The content is checked too; non-images return 415 GL007.
  • Uploaded images are converted to JPEG and shrunk to a long side of 1280px, targeting about 300KB. If an image still exceeds the MMS limit after shrinking, sending may fail, so upload small images when possible.
  • If no files are sent, an empty array is returned.
bash
curl -X POST "https://studio-gateway.zerocall.kr/chat/media/upload" \
  -H "x-api-key: $KAT_API_KEY" \
  -F "files=@coupon.png"
json
Response
{
  "urls": ["chat-media/456/1794812400000-k3j9x2.jpg"]
}
HTTPCodeWhen
400G4004 or more files ("Too many files")
413G413A single file is over 10MB ("File too large")
415GL007Not an image, or an unsupported format
500GL008Storage failed. Upload again after a moment

Message sending

An API that sends a message given only the recipient number. You do not need to open a chat room first. It finds or creates the chat room for your number and the recipient number and records the message there, so sent messages also appear in List messages.

For one-off messages such as reservation confirmations and notices, this API is simpler. If you are building a screen that shows conversations with customers per chat room and lets you reply, use the chat room and chat APIs. Messages sent either way collect in the same room, and results arrive the same way (SEND_RESULT webhook, Get send result).

MethodPathDescription
POST/message/sendSend a message
GET/message/send-result/{chatId}Get send result
POST/message/media/uploadUpload MMS images

Send a message

POST/message/send

The response is the message ID (chatId, 32 characters) as a string (201). Use it to match the SEND_RESULT webhook or to look up the send result.

FieldTypeRequiredDescription
fromPhoneNumberstringYesYour number to send from (a KAT number in your group). Hyphens are removed before reading. 404 CH001 if not a group number
toPhoneNumberstringYesRecipient number. Hyphens are removed before reading
contentstringYesBody, 1–2,000 characters
subjectstringNoSubject. 64 characters or less and 64 bytes or less in EUC-KR (32 Korean characters). 400 CH004 if over the byte limit
imageListstring[]NoList of image keys. Pass the values from the Upload MMS images response to send as MMS (300 characters or less each, no commas)

Message type

TypeCondition
MMSimageList contains at least one image
SMSNo subject, and the body is 90 bytes or less in EUC-KR (Korean characters 2 bytes, English letters and digits 1 byte)
LMSEverything else (has a subject, or the body is over 90 bytes)
json
Request
POST /message/send

{
  "fromPhoneNumber": "070-1234-5678",
  "toPhoneNumber": "010-9876-5432",
  "subject": "Reservation confirmed",
  "content": "Hello. Your reservation for 3 PM on November 18 is confirmed."
}
Response
"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Even when the message could not be handed to the carrier, you get a chatId instead of an error, and the message stays with sendStatus FAILED. Check success or failure with Get send result or the webhook. If the recipient has opted out of advertising messages from your number, the message is not sent and you get 400 CH003.

A group in trial gets 403 KC012 once it has used the messages included in the trial (50). Check what is left in Included usage · usage.

Errors

HTTPCodeWhen
400GL002Invalid body (including a missing or empty fromPhoneNumber)
400CH003Recipient has opted out ("수신거부된 번호입니다." — "This number has opted out.")
400CH004Subject is over 64 bytes
400CH007Contains a blocked word or link
402GR016The group's message sending is blocked due to insufficient balance
403KC012All messages included in the trial are used up
403KC008Trial has ended, or the group's service is paused
403GR076Group suspended under the operating policy
403GL010Message sending restricted under the operating policy
404CH001fromPhoneNumber is not a number in your group ("존재하지 않는 채널이에요!" — "Channel does not exist!")
503CH002That number (channel) cannot send messages right now
The same code means different things in different APIs. 404 CH001means "sending number not found" in Send a message, but "message not found" in Get send result. Interpret 404 CR001 (chat room not found) and 400 CR002 · 400 CH005 (cursor format) together with which API returned them.

Get send result

GET/message/send-result/{chatId}

Gets the current status of a message sent through the API. Works for messages sent with both /message/send and POST /chat. Use it when you do not receive webhooks, or to check the status before the webhook arrives. If the message was not sent through the API in your group, you get 404 CH001("존재하지 않는 문자에요!" — "Message does not exist!").

json
Request
GET /message/send-result/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Response
{
  "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "content": "Hello. Your reservation for 3 PM on November 18 is confirmed.",
  "subject": "Reservation confirmed",
  "imageList": [],
  "fromPhoneNumber": "07012345678",
  "toPhoneNumber": "01098765432",
  "sendStatus": "SUCCESS",
  "chatType": "LMS",
  "resultStatus": "6600",
  "resultMessage": "전달",
  "createdAt": "2026-11-16T01:30:00.000Z"
}
FieldTypeDescription
idstringMessage ID (chatId)
content · subjectstringBody and subject (subject is omitted if there is none)
imageListstring[]Image URLs (temporary URLs generated when the response is built)
externalMessageIdstringexternalMessageId given to POST /chat (only when present)
fromPhoneNumber · toPhoneNumberstringSender number · recipient number
sendStatusstringSUCCESS · FAILED. Omitted if not yet determined
chatTypestringSMS · LMS · MMS · RCS · KAO (in webhooks, KakaoTalk comes as KAKAO)
resultStatusstringCarrier result code. Omitted until the result arrives (result codes)
resultMessagestringMeaning of the result code (for example, 전달 = delivered). Unknown if the code is not in the table
createdAtstringCreation time
Whether the message reached the customer is determined by whether resultStatus is one of 4100 (SMS), 6600 (LMS · MMS), or 7000 (KakaoTalk). If resultStatus is not there yet, check again after a moment.

Upload MMS images

POST/message/media/upload

Put up to 3 files at a time, up to 10MB each, in the files field of multipart/form-data. Accepted formats and conversion rules are the same as chat media upload (images only, converted to JPEG). Pass the keys from the response into imageList of /message/send.

bash
curl -X POST "https://studio-gateway.zerocall.kr/message/media/upload" \
  -H "x-api-key: $KAT_API_KEY" \
  -F "files=@sample1.png" \
  -F "files=@sample2.jpg"
json
Response
{
  "urls": [
    "chat-media/456/1794812400000-k3j9x2.jpg",
    "chat-media/456/1794812400001-p8q1z7.jpg"
  ]
}

Files that failed to store are left out of urls. Compare the number of files you sent with the number of urls and upload the missing ones again.

HTTPCodeWhen
400G400No files ("업로드할 파일이 없습니다." — "No files to upload."), none could be stored ("업로드 가능한 파일이 없습니다." — "No files could be uploaded."), 4 or more files ("Too many files")
413G413A single file is over 10MB ("File too large")
415GL007Not an image, or an unsupported format

Call history

Get the history of inbound and outbound calls (including AI outbound and stream outbound calls). Calls with recording turned on include the recording file, transcript, and summary. To be notified each time a call ends, use the CALL_COMPLETED webhook instead of polling.

MethodPathDescription
GET/call-historyList call history
GET/call-history/{callHistoryId}Get a call history record
POST/group/{groupId}/call-history/counterpart-erasureMask or erase call history for a counterpart number
DELETE/group/{groupId}/call-history/{callHistoryId}Erase one call history record
GET · PUT/group/{groupId}/call-record-privacyGet or set when counterpart numbers are masked automatically

List call history

GET/call-history

Pages with an offset. By default the most recent calls come first; with updatedAfter, only records changed after that time are returned, oldest first (see Incremental sync below). Erased calls are not returned.

FieldTypeRequiredDescription
groupIdnumberYesYour group ID. 403 PK004 if outside the key's scope
channelIdnumberNoOnly calls on this number (channel). Empty list if it is not a number in the group
phoneNumberstringNoSearch by calling or called number (partial matches work)
keywordstringNoSearch summary content
updatedAfterstringNoOnly records changed after this time (ISO 8601). When set, sorted by updatedAt ascending
offsetnumberNo0 or greater, default 0
limitnumberNo1–100, default 20
includeTracksbooleanNoIf true, attaches per-speaker files (customer · agent) to the recording. Default false
json
Request
GET /call-history?groupId=789&limit=20&includeTracks=true
Response
{
  "data": [
    {
      "callHistoryId": "8f3f8fd9-7ab8-4a26-b523-4f8eb7d38b85",
      "fromNumber": "01098765432",
      "toNumber": "07012345678",
      "isInbound": true,
      "status": "ANSWERED",
      "callPhase": "ANSWERED",
      "tag": "AI",
      "duration": 96,
      "summary": "Caller asked to move tomorrow's reservation to 3 PM. Change request taken.",
      "sttAI": [
        { "role": "agent", "text": "Hello. How can I help you?", "timestamp": 1.2 },
        { "role": "customer", "text": "I'd like to change my reservation time for tomorrow.", "timestamp": 4.3 }
      ],
      "recordingAI": {
        "url": "https://storage.example.com/recording/....wav?X-Amz-Signature=...",
        "expiresAt": "2026-11-16T02:40:00.000Z",
        "contentLength": 1234567,
        "contentType": "audio/wav",
        "customer": {
          "url": "https://storage.example.com/recording/....wav?X-Amz-Signature=...",
          "expiresAt": "2026-11-16T02:40:00.000Z",
          "contentLength": 617284,
          "contentType": "audio/wav"
        },
        "agent": {
          "url": "https://storage.example.com/recording/....wav?X-Amz-Signature=...",
          "expiresAt": "2026-11-16T02:40:00.000Z",
          "contentLength": 617283,
          "contentType": "audio/wav"
        }
      },
      "isRecorded": true,
      "channelId": 100,
      "groupId": 789,
      "createdAt": "2026-11-16T01:30:00.000Z",
      "updatedAt": "2026-11-16T01:33:12.000Z"
    }
  ],
  "total": 231,
  "offset": 0,
  "limit": 20
}

Response fields

Fields with no value are omitted from the response.

FieldTypeDescription
callHistoryIdstringCall history ID. The format differs by call type, so store it as a string as-is (table below)
fromNumber · toNumberstringCalling number · called number. Masked numbers look like 010****5678
isInboundbooleantrue for inbound calls, false for outbound calls
callPhasestringCall phase (table below). Use this value to determine the call outcome. Absent on older calls that have no phase record
statusstringANSWERED · MISSED · REJECTED · UNKNOWN (in progress). Kept for older integrations; outbound calls are ANSWERED even when not answered
tagstringAI (AI agent only) · DIRECT (staff only) · AI_TO_DIRECT (AI agent handed off to staff) · UNKNOWN
durationnumberActual connected time (seconds)
summarystringSummary. Present on recorded calls once summarization finishes
sttAI · sttDirectobject[]Transcript. AI agent segment · staff segment. Items are { role: agent | customer, text, timestamp (seconds) }
recordingAI · recordingDirectobjectRecording files. AI agent segment (including stream calls) · staff segment (see Recording files below)
isRecordedbooleanWhether recording was on during the call. If false, there is no summary · stt · recording
connectionstringSTREAM for media stream calls. Otherwise the field is absent
channelId · groupIdnumberYour number (channel) and group used for the call
createdAtstringCall start time
updatedAtstringTime the record last changed. The basis for incremental sync

callPhase

ValueMeaning
RECEIVEDCame in. Not yet connected, or choosing from the menu
AI_TALKINGTalking with the AI agent
QUEUED · RINGING · TALKINGWaiting for staff · ringing (for outbound calls, the counterpart's phone is ringing) · talking with staff
ANSWEREDAnswered call ended
MISSEDNo one answered (for outbound calls, the counterpart did not answer or the connection failed)
ABANDONEDCaller hung up while waiting
REJECTEDRejected
FAILEDConnection failed
BLOCKEDBlocked number; hung up without ringing

The first five values are in progress; the last six are ended states. Calls in progress also appear in the list, so to process only ended calls, check that the state is an ended one.

What each call type looks like

CallcallHistoryIdShape
Inbound call (AI agent · staff)UUID formatisInbound true, fromNumber = customer, toNumber = your number
AI outbound callao + the outbound request ID with hyphens removedSame as callHistoryId in the outbound request response and webhooks. isInbound false, fromNumber = caller ID number, toNumber = recipient number. The record is created when dialing starts; callPhase goes RINGING → AI_TALKING → ANSWERED, or ends as MISSED if not answered
Stream outbound callao + the stream outbound callId with hyphens removedSame shape as AI outbound calls, with connection: STREAM. The recording comes in recordingAI; no transcript or summary is created
Stream inbound callSame value as callId in the status webhookSame shape as inbound calls, with connection: STREAM. The recording comes in recordingAI

Distinguish stream calls by connection, not tag.

Recording files

Attached only to calls with the group's recording setting on that were answered and connected for longer than 0 seconds. If the file is not ready yet, the field is omitted and appears in a later request.

FieldTypeDescription
urlstringDownload URL (WAV)
expiresAtstringURL expiry time
contentLengthnumberFile size (bytes)
contentTypestringaudio/wav
customer · agentobjectOnly when includeTracks=true. A file with only the customer's voice · only the agent's voice (the AI for the AI segment). Same shape as the four fields above
A recording URL works only until expiresAt. URLs are valid for up to 1 hour, but an already-generated URL may be returned again, so it can expire sooner than 1 hour after you receive it. Do not compute the time yourself; check expiresAt. If it has expired, call the list or detail endpoint again to get a new URL. To keep the file, download it right away and store it in your own storage.

Incremental sync

If webhooks are hard to use, fetch only changed records with updatedAfter. The response is sorted by updatedAt ascending. updatedAt changes whenever the record changes, such as when the call phase changes or a transcript or summary is saved, so the same call can come back several times. Overwrite received records by callHistoryId.

  • Set updatedAfter for the next request to 1 second before the updatedAt of the last item you received. Records changed at the same time are not lost at page boundaries, and records that come back again can simply be overwritten.
  • Keep offset at 0 and do not combine it with this. Records that change during the query can shift the order and be skipped.
  • If you receive fewer items than limit, that cycle is done. Store the last reference time and continue from it in the next cycle.
  • Erased calls drop out of the list, so incremental queries cannot tell you a call was erased. Whoever calls erase call history should also erase their own copy.
http
# 1) First run — from the reference time
GET /call-history?groupId=789&updatedAfter=2026-11-16T00:00:00.000Z&limit=100

# 2) If the last item's updatedAt was 2026-11-16T01:33:12.000Z, continue from 1 second earlier
GET /call-history?groupId=789&updatedAfter=2026-11-16T01:33:11.000Z&limit=100

# 3) If you received fewer items than limit, this cycle is done. Store the reference time and call again next cycle

Get a call history record

GET/call-history/{callHistoryId}

Returns one item with the same shape as a list item. Also use it to fetch the transcript, summary, and recording by the callHistoryId of an AI outbound or stream outbound call.

FieldTypeRequiredDescription
groupIdnumberYesYour group ID (query)
includeTracksbooleanNoWhether to attach per-speaker recording files (query, default false)
http
GET /call-history/ao6f1c2a0e1d2b4c3d9e8f0a1b2c3d4e5f?groupId=789

If the call does not exist, was erased, or is not in your group, you get an error (4xx). Do not tell these cases apart by response code; treat them all as "call not available".

Call history personal data requests

Masks numbers in call history or erases records, for example when a customer asks to delete the call history for their number. This cannot be undone.The number of records processed and the key that made the request are kept in KAT Cloud's erasure log; the number itself is not kept.

MethodNumberRecording · transcript · summaryList · detail
Mask counterpart number (MASK)MaskedKeptStill returned (only the number is masked)
Erase counterpart number (DELETE)MaskedErased (including voicemail)Not returned
Erase one callMaskedErased (including voicemail)Not returned
Automatic masking settingMasked N months after the callKeptStill returned (only the number is masked)
  • Numbers are masked except for the first 3 and last 4 digits (010****5678). When a call matches, its calling number, called number, forwarding number, and callback number are all masked.
  • Masking alone keeps the recording, transcript, and summary. The conversation may contain information such as names and addresses, so if a customer asked to delete their records, use DELETE.
  • The recipient number stored on a stream outbound request is masked by the same rule, and that request's metadata is cleared (null).
  • Communication confirmation data (call records such as call time and numbers) is kept for 12 months after the call, as required by law. For calls older than 12 months, the number in the call record is masked immediately; for calls within 12 months, it is masked automatically when the retention period ends. The cdr field in the response gives the counts and the expiry date.

Mask or erase call history for a counterpart number

POST/group/{groupId}/call-history/counterpart-erasure

Finds calls to and from this number across all of the group's numbers (including removed numbers) and masks or erases them. The response is 200.

FieldTypeRequiredDescription
phoneNumberstringYesCounterpart number, 30 characters or less. 010-1234-5678 · 01012345678 · +821012345678 · 821012345678 are treated as the same number. 400 PV001 if not 7–15 digits
modestringYesMASK (mask the number only) or DELETE (mask the number, erase the recording, transcript, and summary, and remove from queries)
dryRunbooleanNoIf true, changes nothing and returns only the target counts. Default false

One request processes up to 5,000 calls for MASK and 500 for DELETE. If remainingCalls in the response is greater than 0, send the same request again until it reaches 0. Calls already processed do not match again, so if a request fails midway you can resume with the same request. Passing a KAT number from your own group would match every call in the group, so it is rejected with 400 PV002.

json
Request
POST /group/789/call-history/counterpart-erasure

{
  "phoneNumber": "010-9876-5432",
  "mode": "DELETE",
  "dryRun": false
}
Response
{
  "groupId": 789,
  "mode": "DELETE",
  "dryRun": false,
  "matchedCalls": 12,
  "processedCalls": 12,
  "remainingCalls": 0,
  "recordingsPurged": 9,
  "cdr": {
    "maskedNow": 3,
    "retained": 9,
    "retainedUntil": "2027-10-02"
  },
  "streamRequests": 1
}
FieldTypeDescription
matchedCallsnumberNumber of target calls not yet processed at the time of the request
processedCallsnumberNumber of calls processed this time (0 for dryRun)
remainingCallsnumberNumber of calls remaining (equal to matchedCalls for dryRun). Send again until it reaches 0
recordingsPurgednumberNumber of calls whose recording, transcript, and summary were erased (DELETE only)
cdr.maskedNownumberNumber of call records older than 12 months masked this time (for dryRun, that would be masked)
cdr.retainednumberNumber of call records kept because they are under legal retention
cdr.retainedUntilstring | nullRetention expiry date of the last kept call record (Korean date, YYYY-MM-DD). Masked automatically from the next day
streamRequestsnumberNumber of stream outbound requests masked (for dryRun, that would be masked)

Erase one call history record

DELETE/group/{groupId}/call-history/{callHistoryId}

Masks all numbers on one call, erases the recording, transcript, summary, and voicemail, and removes it from list and detail queries. If it was a stream outbound call, the recipient number on that request is masked and its metadata is cleared. Safe to call more than once; if the call was already erased, alreadyDeleted is true. A call that does not exist and a call in another group both return 404 PV004.

json
Request
DELETE /group/789/call-history/8f3f8fd9-7ab8-4a26-b523-4f8eb7d38b85
Response
{
  "groupId": 789,
  "callHistoryId": "8f3f8fd9-7ab8-4a26-b523-4f8eb7d38b85",
  "deleted": true,
  "alreadyDeleted": false,
  "cdr": {
    "maskedNow": 0,
    "retained": 1,
    "retainedUntil": "2027-11-16"
  }
}

Automatic counterpart number masking setting

GET/group/{groupId}/call-record-privacy
PUT/group/{groupId}/call-record-privacy

Sets how many months after a call the numbers in its call history are masked. Once a day, numbers on calls past the threshold (and the recipient number and metadata on stream outbound requests) are masked. The recording, transcript, and summary are kept. If not set (null), the default is 36 months.

FieldTypeRequiredDescription
maskCounterpartAfterMonthsnumber | nullYesInteger from 12 to 36, or null (reset to the default 36 months). The field itself must not be omitted (400 GL002). 400 if out of range
json
Request
PUT /group/789/call-record-privacy

{
  "maskCounterpartAfterMonths": 12
}
Response (GET returns the same shape)
{
  "groupId": 789,
  "maskCounterpartAfterMonths": 12,
  "defaultMonths": 36,
  "minMonths": 12,
  "maxMonths": 36
}

You cannot set it shorter than 12 months, because that would overlap the legal retention period for call records (12 months).

Errors

HTTPCodeWhen
400GL002Invalid body (invalid mode value, maskCounterpartAfterMonths missing or out of range, etc.)
400PV001Invalid phone number format (7–15 digits; hyphens and +82 allowed)
400PV002A number connected to your group was given as the counterpart number
400PV005Automatic masking months is not an integer from 12 to 36 or null
403PV003Not a KAT Cloud group
403PK004Group outside the key's scope
404PV004Call to erase not found (does not exist or belongs to another group)

AI outbound calls

An outbound (OUTBOUND) AI agent calls your customer. The request is accepted immediately (202), and dialing, the conversation, and hang-up happen in the background. Get the result through a webhook or by fetching the request details.

MethodPathDescription
POST/group/{groupId}/ai-outbound/callsCreate an outbound call request (202)
GET/group/{groupId}/ai-outbound/callsList outbound call requests
GET/group/{groupId}/ai-outbound/calls/{requestId}Get an outbound call request
POST/group/{groupId}/ai-outbound/calls/{requestId}/terminationHang up (202)

Requirements and limits

Every KAT group can use AI outbound calls without a separate application. Groups whose outbound calling was stopped by an operator, and groups whose trial has ended or whose service is suspended, get 403 AO002. During the trial, at least 1 minute of trial outbound included usage must remain; otherwise 403 AO016.

ItemDefaultWhen exceeded
Calling hours08:00–21:00 Korea time (not allowed from 21:00 sharp)403 AO012
Daily call count (by Korean calendar date)100 calls429 AO014
Concurrent outbound calls1 call429 AO013
Ring time30 seconds (NO_ANSWER if not answered)—
Call durationThe AI agent's maximum call duration, or 480 seconds if not setHung up with MAX_DURATION
AI outbound calls and media stream outbound calls share the calling hours, daily call count, and concurrent outbound call slots. In a group limited to 1 concurrent outbound call, an AI outbound call gets 429 AO013 while a stream outbound call is in progress. Contact us to raise the limits.

Destination numbers

Only domestic (Korean) numbers can be called: 010, 070, 02, and area codes (031–064). Spaces, parentheses, and hyphens are removed, and +82 is read as 0. 011/016, 050X, 15XX representative numbers, and international numbers return 400 AO005. Numbers blocked by the group, or numbers that opted out of calls from this caller number, return 403 AO011.

Caller number

You do not write the caller number in the body; you choose it by the group's phone number (channel) ID. Get the ID from GET /group/{groupId}/channel. The callee sees that channel's caller ID number. If the number is not properly activated, the request returns 400 AO010.

Create an outbound call request

POST/group/{groupId}/ai-outbound/calls

The Idempotency-Key header is required. Resending with the same key does not place a new call and returns the original request unchanged, so you can safely retry when you did not get a response. Sending a different body with the same key returns 409 AO006. The key must be unique within the group and be 1–128 ASCII characters with no spaces (for example, an order number or UUID).

HeaderRequiredDescription
Idempotency-KeyYesYour key identifying one outbound call
FieldTypeRequiredDescription
agentIdnumberYesOutbound AI agent ID. Its direction must be OUTBOUND and it must be ACTIVE (otherwise 404 AO007)
callerChannelIdnumberYesID of the group phone number (channel) to call from
destinationstringYesDomestic (Korean) destination number, up to 32 characters
inputsobjectYesValues for the AI agent's outbound input fields. {} for an AI agent with no input fields

inputs must match the outbound input fields defined on the AI agent. Undefined fields, missing required fields, values of the wrong type (no automatic conversion), strings over 4,000 characters, arrays over 100 items, or more than 16 KB in total return 400 AO005, with the reason in details.reason (for example, inputs.customerName: REQUIRED). Body fields not in the table, or fields of the wrong type (such as sending agentId as a string), return 400 GL002.

The AI agent's settings (instructions, manual, tools, voice, model, maximum call duration) and the group's recording setting are fixed at the moment the request is accepted. Changes to the AI agent after that do not apply to this call.

json
Request
POST /group/789/ai-outbound/calls
Idempotency-Key: order-20261116-0001

{
  "agentId": 11,
  "callerChannelId": 100,
  "destination": "010-1234-5678",
  "inputs": {
    "customerName": "Hong Gildong",
    "deliveryDate": "November 18"
  }
}
Response (202 Accepted)
{
  "requestId": "6f1c2a0e-1d2b-4c3d-9e8f-0a1b2c3d4e5f",
  "agentId": 11,
  "agentVersion": 3,
  "destination": "01012345678",
  "callerChannelId": 100,
  "status": "ACCEPTED",
  "endReason": null,
  "reconciliation": "NONE",
  "analysisStatus": "NOT_APPLICABLE",
  "settlementStatus": "PENDING",
  "finalAmount": null,
  "createdAt": "2026-11-16T01:00:00.000Z",
  "endedAt": null,
  "answeredAt": null,
  "answerEstimated": false,
  "aiStartedAt": null,
  "terminationRequestedAt": null,
  "callHistoryId": null
}

List and get requests

GET/group/{groupId}/ai-outbound/calls
GET/group/{groupId}/ai-outbound/calls/{requestId}

The list is newest first and returns { items, nextCursor }. For the next page, pass the received nextCursor as cursor; when there are no more pages, nextCursor is null. This list also includes stream outbound calls, with agentId set to 0. Groups whose outbound calling is stopped can still list, get, and hang up.

QueryTypeDescription
limitnumber1–100, default 20
cursorstringnextCursor from the previous response

Response fields

FieldTypeDescription
requestIdstringOutbound call request ID (UUID)
agentId · agentVersionnumberAI agent and the version fixed at acceptance
destinationstringDestination number (normalized)
callerChannelIdnumberCaller channel ID
statusstringStatus
endReasonstring | nullEnd reason
reconciliationstringPENDING = checking the dial result with the switch; otherwise NONE
analysisStatusstringNOT_APPLICABLE (not recorded or not connected) · PENDING · READY (transcript + summary) · PARTIAL (transcript only) · FAILED
settlementStatusstringPENDING · SETTLED · WAIVED (waived due to a failure on our side)
finalAmountnumber | null0 only for calls finalized at KRW 0 because they were not answered; null otherwise (see the credit history for amounts)
answeredAtstring | nullTime the call was answered
answerEstimatedbooleantrue if the answer time was estimated from other records
aiStartedAtstring | nullTime the AI agent's first audio went out
terminationRequestedAtstring | nullTime the hang-up was requested
callHistoryIdstring | nullCall history ID. Fetch the recording, transcript, and summary with the call history API (null before dialing)

Hang up

POST/group/{groupId}/ai-outbound/calls/{requestId}/termination

Send with no body. The response has the same shape as the details (202), and repeated requests return the same result.

  • If the request has not been sent to the switch yet, it ends immediately with CANCELED · CUSTOMER_TERMINATED.
  • If the call is already being placed, only terminationRequestedAt is set and returned. Hanging up takes a few seconds, so the status in the response may still be in progress. Check the result with the end webhook or by fetching the details.
  • If you hang up after the call is answered, the status is COMPLETED and the reason is CUSTOMER_TERMINATED.

Statuses and end reasons

statusMeaning
ACCEPTEDAccepted. Ends with DISPATCH_EXPIRED if not dialed within 30 seconds
DIALINGBeing dialed by the switch
RINGINGThe callee's phone is ringing (only when the carrier sends a ringing signal; usually skipped on Korean lines)
CONNECTEDCallee answered
IN_PROGRESSThe AI agent's first audio went out
COMPLETEDEnded after answer (also COMPLETED when ended by the hang-up API, maximum duration, or the AI agent)
NO_ANSWER · BUSY · REJECTEDNo answer · busy · rejected
CANCELEDCanceled before answer by a hang-up request, an operator stop, or the AI agent ending the call
FAILEDFailed. FAILED on a system error, even after answer
endReasonMeaning
REMOTE_HANGUPThe callee hung up
NO_ANSWER · BUSY · REJECTEDNo answer (30-second ring) · busy · rejected
CARRIER_FAILUREFailure on the carrier network
CUSTOMER_TERMINATEDHang-up API (including hang-ups from the console)
MAX_DURATIONMaximum call duration exceeded
AGENT_ENDEDThe AI agent ended the call
SYSTEM_FAILUREError on the KAT Cloud side
DISPATCH_EXPIREDNot dialed within 30 seconds of acceptance
ADMISSION_CHANGEDFailed a condition rechecked just before dialing (calling hours, limits, trial, etc.)
ORIGINATE_REJECTEDThe switch rejected the call
GROUP_SUSPENDEDAn operator stopped outbound calling for the group, canceling requests not yet dialed
If a record that the call was "answered" is confirmed late, after the call ended, a status such as NO_ANSWER can change to COMPLETED. No new webhook is sent in that case, so use the details endpoint for the final values you use for settlement or reporting.

Webhooks

Register eventType AI_OUTBOUND in webhook settings to receive the two events below. There are no progress events such as ringing or answer. If no webhook is registered when an event occurs, that event is not sent (registering later does not deliver past events). On failure, the event is resent twice more, 5 and 10 seconds later, with the same eventId. Use data.sequence to order events within one request.

data.typeWhen
ai_outbound.call.endedOnce, when the call ends (including unanswered calls)
ai_outbound.analysis.completedOnce, when the transcript and summary of a recorded call are ready
json
Event ai_outbound.call.ended
{
  "eventId": "c2b9d8a4-5e1f-4a3b-9c7d-1e2f3a4b5c6d",
  "eventType": "AI_OUTBOUND",
  "timestamp": "2026-11-16T01:03:11.000Z",
  "data": {
    "type": "ai_outbound.call.ended",
    "sequence": 1,
    "schemaVersion": 1,
    "occurredAt": "2026-11-16T01:03:10.000Z",
    "requestId": "6f1c2a0e-1d2b-4c3d-9e8f-0a1b2c3d4e5f",
    "callHistoryId": "ao6f1c2a0e1d2b4c3d9e8f0a1b2c3d4e5f",
    "status": "COMPLETED",
    "endReason": "REMOTE_HANGUP",
    "answered": true,
    "answeredAt": "2026-11-16T01:00:12.000Z",
    "endedAt": "2026-11-16T01:03:10.000Z",
    "durationSeconds": 178,
    "analysisStatus": "PENDING",
    "settlementStatus": "PENDING"
  }
}
Event ai_outbound.analysis.completed
{
  "eventId": "0b7e4f21-8c3d-4e5a-b6f7-a8b9c0d1e2f3",
  "eventType": "AI_OUTBOUND",
  "timestamp": "2026-11-16T01:04:02.000Z",
  "data": {
    "type": "ai_outbound.analysis.completed",
    "sequence": 2,
    "schemaVersion": 1,
    "occurredAt": "2026-11-16T01:04:01.000Z",
    "requestId": "6f1c2a0e-1d2b-4c3d-9e8f-0a1b2c3d4e5f",
    "analysisStatus": "READY",
    "transcript": "READY",
    "summary": "READY"
  }
}

durationSeconds runs from answer to end (rounded up to the second) and is 0 if the call was not answered. The webhook does not include the transcript or summary text; fetch the call history details with callHistoryId.

Pricing

  • Only answered calls are charged. Unanswered calls cost KRW 0.
  • Answered calls: outbound call fee (rounded up to 1 minute per call) + AI agent per-minute fee + transcript and summary fees for recorded calls. During the trial, usage is deducted from the trial outbound included usage in 1-minute units.
  • If the call ends because of a KAT Cloud issue after answer but before the AI agent's first audio goes out, no charge applies (settlementStatus WAIVED).

Media stream

Streams call audio to your WebSocket server in real time and plays the audio your server sends back into the call. Use it to connect your own voice AI or contact center system directly to a KAT number. It works for both outbound calls (stream outbound) and inbound calls (stream inbound). KAT Cloud acts as the WebSocket clientand connects to your server's wss:// URL.

MethodPathDescription
POST/group/{groupId}/media-stream/callsPlace a stream outbound call (202)
GET/group/{groupId}/media-stream/calls/{callId}Stream outbound call status
POST/group/{groupId}/media-stream/calls/{callId}/terminationHang up a stream outbound call (202)
GET/group/{groupId}/media-stream/inboundList stream inbound settings
PUT/group/{groupId}/media-stream/inbound/{number}Set a stream inbound webhook on a number
DELETE/group/{groupId}/media-stream/inbound/{number}Remove a stream inbound webhook
Media streams are configured through the API only (there is no console screen). Stream calls are charged call fees only, with no AI agent per-minute fee. Transcript and summary fees apply only to recorded inbound calls; stream outbound calls do not produce a transcript or summary even when recorded.

Stream outbound

POST/group/{groupId}/media-stream/calls

When the callee answers, KAT Cloud connects to streamUrl and exchanges audio. Calling hours, daily call count, concurrent outbound calls, trial conditions, and destination number rules are the same as AI outbound calls, and the two share those limits. In addition, each group can have up to 10 concurrent stream calls (outbound plus in-progress inbound).

The Idempotency-Key header is optional. If you send it, a retry with the same key does not place a new call and returns the original request; a different body with the same key returns 409 AO006. Without it, every retry places a new call.

FieldTypeRequiredDescription
fromstringYesCaller number. A 070 number of the group, or a caller ID number attached to that number. 404 AO021 if it is not a group number
tostringYesDomestic (Korean) destination number
streamUrlstringYesWebSocket URL to connect to. wss:// only, up to 500 characters, must resolve to a public IP
statusCallbackUrlstringNoStatus webhook URL for this call (http or https). If omitted, the MEDIA_STREAM webhook is used
metadataobjectNoUp to 4,096 bytes. Passed as-is in customParameters of the start message and in status webhooks
timeLimitnumberNoMaximum call duration after answer, in seconds. 10–14400, default 3600
codecstringNoPCMU (default, μ-law) or PCMA (A-law)
json
Request
POST /group/789/media-stream/calls
Idempotency-Key: campaign-42-01098765432

{
  "from": "07012345678",
  "to": "01098765432",
  "streamUrl": "wss://voice.example.com/stream",
  "statusCallbackUrl": "https://api.example.com/kat/status",
  "metadata": { "customerId": "c-123" },
  "timeLimit": 600
}
Response (202 Accepted)
{
  "callId": "3f0c6c9e-6a1e-4b8e-9d0a-2b1f7c6e1a10",
  "direction": "outbound",
  "from": "07012345678",
  "to": "01098765432",
  "status": "queued",
  "reason": null,
  "streamUrl": "wss://voice.example.com/stream",
  "statusCallbackUrl": "https://api.example.com/kat/status",
  "metadata": { "customerId": "c-123" },
  "codec": "PCMU",
  "createdAt": "2026-11-16T01:00:00.000Z",
  "answeredAt": null,
  "endedAt": null,
  "durationSeconds": 0,
  "callHistoryId": null
}

Get status and hang up

GET/group/{groupId}/media-stream/calls/{callId}
POST/group/{groupId}/media-stream/calls/{callId}/termination

The response has the same shape as above. Send the hang-up request with no body. If the call has not been placed yet, it becomes canceled immediately; if it is dialing or in progress, it is hung up within a few seconds and the reason becomes CUSTOMER_TERMINATED.

statusMeaning
queuedAccepted (dialed within 30 seconds)
initiatedDialing
ringingRinging signal received (usually skipped on Korean lines)
in-progressCallee answered
completedEnded after answer
busy · no-answer · rejected · canceledEnded without answer
failedFailed. Also failed when the call ends after answer because connecting to your server failed or because of a KAT Cloud error

reason uses the same values as AI outbound end reasons, plus two stream-specific reasons: STREAM_CONNECT_FAILED (connecting to streamUrl failed after answer — call fees apply for the answered time) and STREAM_ENDED (your server closed the socket).

Stream inbound

PUT/group/{groupId}/media-stream/inbound/{number}

Sets an incoming-call webhook on your 070 number. Starting with the next call, calls to this number go through the webhook before any AI agent or IVR, and your server decides whether to accept them. A second PUT to the same number overwrites the setting. number must be a 070 number of the group (caller ID numbers are not allowed; otherwise 404 AO021). Hyphens and a +82 prefix are accepted.

FieldTypeRequiredDescription
webhookUrlstringYesURL to call when a call comes in (public http or https URL, up to 500 characters)
statusCallbackUrlstringNoStatus webhook URL for calls to this number
json
Request
PUT /group/789/media-stream/inbound/070-1234-5678
{
  "webhookUrl": "https://api.example.com/kat/incoming",
  "statusCallbackUrl": "https://api.example.com/kat/status"
}
Response
{
  "number": "07012345678",
  "webhookUrl": "https://api.example.com/kat/incoming",
  "statusCallbackUrl": "https://api.example.com/kat/status",
  "enabled": true,
  "updatedAt": "2026-11-16T01:00:00.000Z"
}

Numbers received over a SIP trunk and groups whose answering mode is "Staff only" return 400 AO005. To list settings, use GET /group/{groupId}/media-stream/inbound (an array of the shape above); to remove one, use DELETE /group/{groupId}/media-stream/inbound/{number} (response { "number": "07012345678", "removed": true }). After removal, the next call is handled by the original flow.

Incoming-call webhook (KAT Cloud → your server)

When a call comes in, KAT Cloud sends the request below to webhookUrl and waits 5 seconds for a response. It is not retried. The signature headers are the same as in Webhook signature.

json
Request (KAT Cloud → webhookUrl)
{
  "eventId": "8a7f3c1e-2b4d-4e6f-8a9b-0c1d2e3f4a5b",
  "eventType": "MEDIA_STREAM",
  "timestamp": "2026-11-16T01:00:00.000Z",
  "data": {
    "type": "media_stream.call.incoming",
    "schemaVersion": 1,
    "occurredAt": "2026-11-16T01:00:00.000Z",
    "callId": "5d1b2e7a-9c3f-4a1b-8e2d-6f7a8b9c0d1e",
    "direction": "inbound",
    "from": "01098765432",
    "to": "07012345678"
  }
}
Response (accept)
{
  "action": "stream",
  "streamUrl": "wss://voice.example.com/stream",
  "statusCallbackUrl": "https://api.example.com/kat/status",
  "metadata": { "lang": "ko" },
  "codec": "PCMU"
}
Response (reject)
{ "action": "reject", "reason": "busy" }
Response fieldRule
actionstream or reject
streamUrlRequired for stream. Same wss rules as stream outbound
statusCallbackUrlOptional. Takes precedence over the value in the number setting
metadataOptional object, up to 4,096 bytes. Sent as customParameters in start
codecOptional. PCMU (default) or PCMA
reasonFor reject: "busy" hangs up with a busy signal; anything else hangs up with a reject signal

If there is no response within 5 seconds (WEBHOOK_TIMEOUT), the status is not 2xx (WEBHOOK_FAILED), or the format is invalid (WEBHOOK_INVALID_RESPONSE), the call is hung up without being answered. If connecting to streamUrl fails, the call is also hung up without being answered (STREAM_CONNECT_FAILED). Because the call is answered only after the connection succeeds, inbound calls that end before answer incur no call fees. If concurrent stream calls are at the limit, no webhook is sent and the call is hung up with a busy signal (CAPACITY_EXCEEDED).

Status webhooks

Call progress arrives as eventType: "MEDIA_STREAM" webhooks. The destination is chosen in this order: the call's statusCallbackUrl → (for inbound) the number setting's statusCallbackUrl → the webhook registered for MEDIA_STREAM. If none exists, nothing is sent.

data.typeWhenAdditional fields
media_stream.call.ringingOutbound only, when a ringing signal is received—
media_stream.call.answeredOn answeransweredAt
media_stream.call.completedEnded after answerreason, answeredAt, endedAt, durationSeconds
media_stream.call.failedEnded without answerSame (answeredAt null, durationSeconds 0)
json
Event media_stream.call.completed
{
  "eventId": "e1c4a9b2-7d3f-4c5e-8a1b-2c3d4e5f6a7b",
  "eventType": "MEDIA_STREAM",
  "timestamp": "2026-11-16T01:05:01.000Z",
  "data": {
    "type": "media_stream.call.completed",
    "sequence": 2,
    "schemaVersion": 1,
    "occurredAt": "2026-11-16T01:05:00.000Z",
    "callId": "3f0c6c9e-6a1e-4b8e-9d0a-2b1f7c6e1a10",
    "callHistoryId": "ao3f0c6c9e6a1e4b8e9d0a2b1f7c6e1a10",
    "direction": "outbound",
    "from": "07012345678",
    "to": "01098765432",
    "status": "completed",
    "metadata": { "customerId": "c-123" },
    "reason": "REMOTE_HANGUP",
    "answeredAt": "2026-11-16T01:00:10.000Z",
    "endedAt": "2026-11-16T01:05:00.000Z",
    "durationSeconds": 290
  }
}
Determine the call result from data.status and data.reason, not from the event name. If an outbound call is answered but connecting to your server fails, a media_stream.call.completed event arrives with status: "failed" and reason: "STREAM_CONNECT_FAILED".
  • Outbound events are resent twice more, 5 and 10 seconds after a failure. eventId is a UUID.
  • Inbound events are sent up to three times: immediately, then after 2 and 5 seconds. eventId is "{callId}:{type}". Inbound calls have no ringing event.
  • Inbound reasons: REMOTE_HANGUP (→ status canceled if before answer), REJECTED_BY_CUSTOMER (→ rejected), CAPACITY_EXCEEDED (→ busy), GROUP_CLOSED, WEBHOOK_TIMEOUT, WEBHOOK_FAILED, WEBHOOK_INVALID_RESPONSE, STREAM_CONNECT_FAILED, STREAM_ENDED, SYSTEM_FAILURE.
  • For inbound calls, callId is the same as the call history ID. For outbound calls, the call history ID is callHistoryId.

WebSocket messages

WSKAT Cloud → streamUrl (wss://)

Connection

For outbound calls, KAT Cloud connects after the callee answers; for inbound calls, after the incoming-call webhook response (before the call is answered). The connection timeout is 5 seconds, and redirects are not followed. The connection request carries the headers below, so verify the signature before accepting the connection. If you need a separate token, you can put it in the streamUrl query string.

HeaderValue
X-Kat-Call-IdCall ID (same as start.callId)
X-Kat-Stream-IdStream ID (same as start.streamId, MZ + 32 characters)
X-Webhook-TimestampUnix time (seconds)
X-Webhook-Signaturev1= + HMAC-SHA256(webhook secret, "{timestamp}.{callId}.{streamId}") in hex

Audio format

  • G.711 8 kHz mono. PCMU (μ-law, default) or PCMA (A-law), base64-encoded in JSON.
  • KAT Cloud sends the other party's audio as one message every 20 ms (160 bytes).
  • Audio your server sends has no length limit, but 20 ms chunks are recommended. If audio waiting for playback exceeds 60 seconds, the overflowing messages are dropped.

KAT Cloud → your server

One JSON object per text frame. sequenceNumber is a string that increases by 1 with each message KAT Cloud sends, and start is "1". connected has no sequenceNumber or streamSid.

eventWhen
connectedOnce, right after connecting
startOnce, when call audio is connected (after the call-start announcement, if any)
mediaEvery 20 ms of the other party's audio
dtmfThe other party pressed a keypad key (0-9 * #)
markAll audio sent before your mark has finished playing (immediately on clear)
stopThe call ended. The socket is then closed (code 1000)
json
Message connected
{ "event": "connected", "protocol": "Call", "version": "1.0.0" }
Message start
{
  "event": "start",
  "sequenceNumber": "1",
  "streamSid": "MZ5c0e2b1a9d8e4f7a6b5c4d3e2f1a0b9c",
  "start": {
    "streamId": "MZ5c0e2b1a9d8e4f7a6b5c4d3e2f1a0b9c",
    "callId": "3f0c6c9e-6a1e-4b8e-9d0a-2b1f7c6e1a10",
    "accountId": "KAT789",
    "streamSid": "MZ5c0e2b1a9d8e4f7a6b5c4d3e2f1a0b9c",
    "callSid": "3f0c6c9e-6a1e-4b8e-9d0a-2b1f7c6e1a10",
    "accountSid": "KAT789",
    "tracks": ["inbound"],
    "mediaFormat": { "encoding": "audio/x-mulaw", "sampleRate": 8000, "channels": 1 },
    "customParameters": { "customerId": "c-123" },
    "direction": "outbound",
    "from": "07012345678",
    "to": "01098765432"
  }
}
Message media
{
  "event": "media",
  "sequenceNumber": "2",
  "streamSid": "MZ5c0e2b1a9d8e4f7a6b5c4d3e2f1a0b9c",
  "media": { "track": "inbound", "chunk": "1", "timestamp": "20", "payload": "f39/fn5+…" }
}
Message dtmf
{ "event": "dtmf", "sequenceNumber": "40", "streamSid": "MZ5c…", "dtmf": { "digit": "1", "track": "inbound_track" } }
Message mark
{ "event": "mark", "sequenceNumber": "41", "streamSid": "MZ5c…", "mark": { "name": "greeting-end" } }
Message stop
{
  "event": "stop",
  "sequenceNumber": "99",
  "streamSid": "MZ5c…",
  "stop": { "accountId": "KAT789", "callId": "3f0c…", "accountSid": "KAT789", "callSid": "3f0c…" }
}
  • accountId is KAT + the group ID. streamSid, callSid, and accountSid repeat the same values for Twilio Media Streams compatibility.
  • mediaFormat.encoding is audio/x-alaw for PCMA. customParameters is the metadata from the request or webhook response, or {} if none.
  • media.chunk starts at 1 and increases; a missing number means a lost chunk. media.timestamp is the elapsed ms since start.
  • For outbound calls, from is your caller number and to is the callee. For inbound calls, from is the caller and to is your KAT number.

Your server → KAT Cloud

All messages sent before you receive start are dropped. Unknown events, malformed messages, and binary frames are ignored, and the call continues. You do not need to include streamSid.

eventBodyBehavior
media{"event":"media","media":{"payload":"<base64>"}}Plays the audio to the other party
mark{"event":"mark","mark":{"name":"greeting-end"}}Returns a mark with the same name once all previously sent audio has played (name up to 200 characters)
clear{"event":"clear"}Drops all audio not yet played and immediately returns any pending marks (for barge-in handling)
dtmf{"event":"dtmf","dtmf":{"digit":"1"}}Sends a keypad tone to the other party after all previously sent audio has played. One digit at a time, up to 10 per second
There is no hang-up message. When your server closes the socket, the call is hung up (STREAM_ENDED). To end an inbound call from your server, also close the socket. Each message KAT Cloud receives can be up to 1 MB.

How calls end

CauseOutbound reasonInbound reason
Other party hung upREMOTE_HANGUPREMOTE_HANGUP
Your server closed the socketSTREAM_ENDEDSTREAM_ENDED
Connecting to streamUrl failedSTREAM_CONNECT_FAILED (after answer, so call fees apply)STREAM_CONNECT_FAILED (not answered)
Hang-up APICUSTOMER_TERMINATED—
timeLimit exceededMAX_DURATION— (no duration limit for inbound)
KAT Cloud errorSYSTEM_FAILURESYSTEM_FAILURE

Example server

javascript
// WebSocket server that receives the media stream (Node.js, ws package)
const crypto = require('crypto');
const { WebSocketServer } = require('ws');

const SECRET = process.env.KATCLOUD_WEBHOOK_SECRET; // value from GET /webhook/secret (whsec_…)

function verifyUpgrade(req) {
  const ts = req.headers['x-webhook-timestamp'];
  const callId = req.headers['x-kat-call-id'];
  const streamId = req.headers['x-kat-stream-id'];
  const given = req.headers['x-webhook-signature'] || '';
  if (!ts || !callId || !streamId) return false;
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected =
    'v1=' + crypto.createHmac('sha256', SECRET).update(`${ts}.${callId}.${streamId}`).digest('hex');
  return given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

const wss = new WebSocketServer({
  port: 8080,
  verifyClient: ({ req }) => verifyUpgrade(req),
});

wss.on('connection', (ws) => {
  let streamSid = null;

  ws.on('message', (raw) => {
    const msg = JSON.parse(raw.toString());
    switch (msg.event) {
      case 'connected':
        break; // Connection confirmed. Do not send audio yet
      case 'start':
        streamSid = msg.streamSid;
        console.log('call started', msg.start.callId, msg.start.customParameters);
        break;
      case 'media': {
        const audio = Buffer.from(msg.media.payload, 'base64'); // 20 ms, 160 bytes of G.711
        // Speech recognition and AI processing … send the reply audio back in the same codec
        // ws.send(JSON.stringify({ event: 'media', media: { payload: reply.toString('base64') } }));
        break;
      }
      case 'dtmf':
        console.log('keypad', msg.dtmf.digit);
        break;
      case 'mark':
        console.log('playback finished', msg.mark.name);
        break;
      case 'stop':
        console.log('call ended', streamSid);
        break;
    }
  });
});

// To hang up, call ws.close() — when the socket closes, KAT Cloud hangs up the call (STREAM_ENDED)

AI agents

Create your own AI agents in a group. An inbound (INBOUND) agent is bound to a phone number and answers calls to that number. An outbound (OUTBOUND) agent calls customers through AI outbound calls. Each agent has its own instructions (role, goals, tone), reference information, dedicated manuals, and tools that call your systems during a call. Details the agent records can be received right away through the INTAKE webhook.

Only groups with the AI agent feature turned on can use these APIs. The APIs in this section (agents, manuals, number binding, tools) require the AI agent feature to be on for the group, in addition to the usage scope. If it is off, you get 403 AG002; contact us in that case. If the groupId in the path is not your KAT group, you get 403 PK004.

Outbound agents and their manuals, tools, and number bindings can only be managed in groups that can use AI outbound calls. Otherwise you get 403 AO002.

Agents created on the Agents screen in the console also appear in this API as they are (inbound agents and AI outbound agents are on separate tabs).

MethodPathDescription
POST/group/{groupId}/agentCreate agent (201, 20 per group)
GET/group/{groupId}/agentList agents
GET/group/{groupId}/agent/{agentId}Get agent
PATCH/group/{groupId}/agent/{agentId}Update agent
DELETE/group/{groupId}/agent/{agentId}Delete agent
GET/group/{groupId}/agent/{agentId}/revisionRevision history

What differs by direction

Inbound (INBOUND)Outbound (OUTBOUND)
Call startThe caller dials a bound number (number binding)The agent places the call through an AI outbound call request
greetingFirst greeting, read exactly as written right after the call connectsGuidance for the opening line, not read verbatim. The agent follows it for its opening line, but first states the company name and that it is an AI agent
Outbound input fieldsNot usedoutboundInputSchema defines the values each outbound call request receives
Number bindingRequiredNot used. The caller number is chosen with callerChannelId in the outbound call request
Transfer to a personFollows the group's call forwarding number settingNot done

Create and manage agents

POST/group/{groupId}/agent

Creates the agent as version 1 and records it in the revision history. On success, returns 201 and the agent object. Up to 20 agents can be created per group (400 AG009).

FieldTypeRequiredDescription
namestringRequiredAgent name (100 characters or fewer)
directionstringRequiredINBOUND for inbound calls / OUTBOUND for outbound calls. Cannot be changed after creation
promptstringRequiredRole, goals, tone, and prohibited actions (8,000 characters or fewer)
statusstringOptionalACTIVE (default) / DISABLED — not used for calls
contextstring | nullOptionalBackground information such as company and products (8,000 characters or fewer)
greetingstring | nullOptionalFirst greeting or opening-line guidance (600 characters or fewer). Meaning differs by direction (see greeting below)
voicestring | nullOptionalHIGH_FEMALE · LOW_FEMALE · HIGH_MALE · LOW_MALE. If empty, the group voice is used
languagestring | nullOptionalKO · EN · JA · ZH · TH. If empty, the group default language is used
liveModelstring | nullOptionalVoice model. Currently only gemini-3.8-live can be selected. If empty, calls use the default model, which may change. Setting gemini-3.8-live is recommended (agents created in the console also use this value)
maxCallSecondsnumber | nullOptionalMaximum call duration (seconds, 30–480). If empty, 480
aiInterruptionEnabledboolean | nullOptionalInterruption. If true, the agent stops speaking when the caller talks. If empty, the group setting is used. On calls where the agent's voice feeds back into the caller's microphone, such as speakerphone, the agent may stop at its own voice
outboundInputSchemaobject | nullOptionalOUTBOUND only. Schema of the values each AI outbound call request receives (outbound input fields). Sending it to an INBOUND agent returns 400 AO005

greeting

  • INBOUND — When the call connects, the agent reads the text exactly as written. {지점명}(“branch name”) is replaced with the group name. If empty, the group greeting is used; if that is also empty, the agent gives a short greeting.
  • OUTBOUND— Not read verbatim. It is guidance on how to open the call (for example, “Say this is a call to confirm tomorrow’s reservation”). Whatever the guidance, the agent first states the company name (group name) and that it is an AI agent in its opening line.
json
Request
{
  "name": "Reservation agent",
  "direction": "INBOUND",
  "prompt": "You are a restaurant reservation agent. Take new reservations, changes, and cancellations, and answer menu questions only from the reference information. Do not promise discounts.",
  "context": "Open 11:00–22:00, closed every Monday. Group seating up to 12 people.",
  "greeting": "Hello, this is {지점명}. How can I help you?",
  "voice": "HIGH_FEMALE",
  "liveModel": "gemini-3.8-live",
  "maxCallSeconds": 300
}
Response (201)
{
  "id": 7,
  "outboundInputSchema": null,
  "groupId": 1,
  "name": "Reservation agent",
  "direction": "INBOUND",
  "status": "ACTIVE",
  "prompt": "You are a restaurant reservation agent. ...",
  "context": "Open 11:00–22:00, closed every Monday. Group seating up to 12 people.",
  "greeting": "Hello, this is {지점명}. How can I help you?",
  "voice": "HIGH_FEMALE",
  "language": null,
  "liveModel": "gemini-3.8-live",
  "maxCallSeconds": 300,
  "aiInterruptionEnabled": null,
  "version": 1,
  "createdAt": "2026-11-16T05:00:00.000Z",
  "updatedAt": "2026-11-16T05:00:00.000Z"
}

Response fields

The request fields plus the fields below. Optional fields left empty are returned as null, in which case the group value or default is used.

FieldTypeDescription
idnumberAgent ID (agentId)
groupIdnumberGroup ID
versionnumberAgent version. Increases by 1 whenever the agent body, manuals, or tools change
createdAtstringCreation time (ISO 8601)
updatedAtstringLast update time (ISO 8601)
GET/group/{groupId}/agent

Returns the group’s agents as an array of agent objects. Deleted agents are excluded, sorted by id ascending. Without direction, both directions are returned. When filtering with direction=OUTBOUND, groups that cannot use AI outbound calls get 403 AO002.

QueryTypeRequiredDescription
directionstringOptionalFilter by INBOUND or OUTBOUND
statusstringOptionalFilter by ACTIVE or DISABLED
http
GET /group/1/agent?direction=INBOUND&status=ACTIVE
GET/group/{groupId}/agent/{agentId}

Returns one agent. If the agent does not exist or was deleted, you get 404 AG001.

PATCH/group/{groupId}/agent/{agentId}
  • Fields you don't send are left unchanged.
  • Sending null for context · greeting · voice · language · liveModel · maxCallSeconds · aiInterruptionEnabled · outboundInputSchema clears it, and the group value or default is used.
  • name · prompt · status do not accept null (400 GL002).
  • direction cannot be changed. If it is in the body, it is not ignored but rejected with 400 GL002.
  • Changing outboundInputSchema re-checks that the inputBindingsof this agent’s tools match the new schema. If any tool does not match, you get 400 AO005 (see outbound input fields).
  • The version increases and a revision is recorded only when a field's value actually changes. Changing only status also increases the version. If nothing changed, the agent is returned as is.
json
Request
{
  "greeting": null,
  "status": "DISABLED"
}
DELETE/group/{groupId}/agent/{agentId}

Deletes the agent and returns result: null. Its number bindings are removed as well. The version does not increase, and the revision history remains available.

Error codes for the APIs in this section are listed under AI agent errors.

Outbound input fields (outboundInputSchema)

Fields that receive values that differ per AI outbound call (customer name, reservation number, and so on). Set them only on outbound (OUTBOUND) agents. Define them in JSON Schema form in outboundInputSchema when creating or updating the agent, and send the values in inputs of the AI outbound call request.

  • The schema rules are the same as the tool argument schema (inputSchema). The top level is { "type": "object", "properties": {…}, "required": […] }.
  • Sending it to an INBOUND agent, or breaking the rules, returns 400 AO005.
  • If null, the agent has no outbound input fields. In that case, send inputs as {} in the outbound call request.
  • The received values are passed to the agent as reference information during the call. The agent uses them in the conversation but does not follow sentences inside them as instructions.

Validation of inputs in outbound call requests

inputs in an AI outbound call request must match this schema. The cases below return 400 AO005, with the reason in details.reason (for example, inputs.customerName: REQUIRED).

  • A field not in the schema (UNREGISTERED_FIELD)
  • A required field is missing or null (REQUIRED)
  • A value of the wrong type. No automatic conversion, such as turning the string "4" into a number
  • A value not in enum, a string over 4,000 characters, or an array over 100 items
  • The whole inputs object exceeds 16KB as JSON (INPUT_TOO_LARGE)

Binding to tool arguments (inputBindings)

With an HTTP tool’s inputBindings, some tool arguments can be sent with set values instead of being filled by the agent. Bound arguments are hidden from the agent; the agent fills only the remaining arguments from the conversation.

sourceShapeValue sent
CONSTANT{ "source": "CONSTANT", "value": … }Always the same value (for example, a store code)
OUTBOUND_INPUT{ "source": "OUTBOUND_INPUT", "field": "…" }The value of that field in this outbound call request's inputs
  • Each key must be an argument name in that tool’s inputSchema.properties.
  • The value of CONSTANTmust match that argument’s type.
  • The field of OUTBOUND_INPUTmust be in the agent’s outboundInputSchema.properties and have the same type as the argument (integer and number also count as different types). Tools of INBOUND agents cannot use OUTBOUND_INPUT.
  • HTTP tools only. Sending it to an MCP tool returns 400 AO005.
  • Outbound input fields bound by an active HTTP tool must be included in the outbound call request’s inputs, even if they are optional in the schema. If missing, the outbound call request returns 400 AO005. It is safer to list bound fields in required.
json
Request: create agent — POST /group/1/agent
{
  "name": "Reservation confirmation call",
  "direction": "OUTBOUND",
  "prompt": "Confirm the reservation with the customer one day before. If the customer wants to cancel, take the cancellation.",
  "greeting": "Say this is a call to confirm tomorrow's reservation and confirm the customer's name.",
  "liveModel": "gemini-3.8-live",
  "outboundInputSchema": {
    "type": "object",
    "properties": {
      "customerName": { "type": "string", "description": "Customer name" },
      "reservationId": { "type": "string", "description": "Reservation number" },
      "partySize": { "type": "integer", "description": "Party size" }
    },
    "required": ["customerName", "reservationId"]
  }
}
Request: create tool — POST /group/1/agent/11/tool
{
  "name": "reservation_update",
  "description": "Records the result when the customer confirms or cancels the reservation.",
  "url": "https://api.example.com/reservations/answer",
  "httpMethod": "POST",
  "inputSchema": {
    "type": "object",
    "properties": {
      "storeId": { "type": "string" },
      "reservationId": { "type": "string" },
      "answer": { "type": "string", "enum": ["CONFIRM", "CANCEL"] }
    },
    "required": ["storeId", "reservationId", "answer"]
  },
  "inputBindings": {
    "storeId": { "source": "CONSTANT", "value": "S-01" },
    "reservationId": { "source": "OUTBOUND_INPUT", "field": "reservationId" }
  },
  "write": true
}
Request: inputs of an AI outbound call — POST /group/1/ai-outbound/calls
{
  "customerName": "Minji Kim",
  "reservationId": "R-2041",
  "partySize": 4
}

In this example, the agent fills only answer. Your server receives { "storeId": "S-01", "reservationId": "R-2041", "answer": "CONFIRM" }.

inputBindings errors

If bindings do not match when creating or updating a tool, or when changing the agent’s outboundInputSchema, you get 400 AO005 with the reason in details.reason.

details.reasonMeaning
INVALID_BINDINGSinputBindings is not an object, or the tool inputSchema breaks the rules
INVALID_BINDING_TARGETArgument name not in inputSchema
INVALID_BINDINGA CONSTANT entry has keys other than source · value
UNREGISTERED_BINDING_INPUTThe OUTBOUND_INPUT field is not in the outbound input fields (including when the agent is INBOUND or has no outbound input fields)
BINDING_TYPE_MISMATCHThe outbound input field and the tool argument have different types
INVALID_BINDING_SOURCEsource is not CONSTANT · OUTBOUND_INPUT
inputs.<argument>: …The CONSTANT value does not match the argument type (for example, inputs.storeId: STRING_REQUIRED)
json
Response (400)
{
  "status": 400,
  "code": "AO005",
  "message": "발신 입력 또는 제한 설정이 올바르지 않습니다.",
  "details": { "reason": "BINDING_TYPE_MISMATCH" }
}

Revision history

GET/group/{groupId}/agent/{agentId}/revision

Returns up to the latest 50 revisions by version, in descending version order. The history of deleted agents can also be retrieved. Call history and the CALL_COMPLETED webhook record agentId · agentVersion, so you can look up which settings a call used in this history.

json
Response
[
  {
    "version": 3,
    "snapshot": {
      "direction": "INBOUND",
      "name": "Reservation agent",
      "status": "ACTIVE",
      "prompt": "You are a restaurant reservation agent. ...",
      "context": "Open 11:00–22:00, closed every Monday. Group seating up to 12 people.",
      "greeting": "Hello, this is {지점명}. How can I help you?",
      "voice": "HIGH_FEMALE",
      "language": null,
      "liveModel": "gemini-3.8-live",
      "maxCallSeconds": 300,
      "aiInterruptionEnabled": null,
      "outboundInputSchema": null,
      "manuals": [
        {
          "id": 12,
          "name": "Reservations",
          "description": "When the customer wants to make, change, or cancel a reservation",
          "content": "Reservations are accepted only for dates within 30 days from today. ...",
          "manualKind": "NOTE",
          "noteFields": [{ "key": "date", "label": "Date", "type": "DATE" }],
          "noteHandoffEnabled": false,
          "isActive": true
        }
      ],
      "tools": [
        {
          "id": 3,
          "kind": "HTTP",
          "name": "order_status",
          "description": "Looks up the shipping status by order number.",
          "url": "https://api.example.com/orders/status",
          "httpMethod": "GET",
          "inputSchema": { "type": "object", "properties": { "orderNo": { "type": "string" } }, "required": ["orderNo"] },
          "inputBindings": null,
          "authVersion": 1,
          "authType": "BEARER",
          "authHeaderName": null,
          "hasAuthSecret": true,
          "timeoutMs": 5000,
          "write": false,
          "mcpAllowedTools": null,
          "isActive": true
        },
        {
          "id": 4,
          "kind": "MCP",
          "name": "shop",
          "description": "Order lookup and cancellation.",
          "url": "https://mcp.example.com/mcp",
          "httpMethod": null,
          "inputSchema": null,
          "inputBindings": null,
          "authVersion": 1,
          "authType": "BEARER",
          "authHeaderName": null,
          "hasAuthSecret": true,
          "timeoutMs": 5000,
          "write": false,
          "mcpAllowedTools": ["get_order"],
          "mcpTools": [{ "name": "get_order", "readOnly": true, "usable": true }],
          "isActive": true
        }
      ]
    },
    "changedApiKeyId": null,
    "createdAt": "2026-11-16T05:10:00.000Z"
  }
]

Response fields

FieldTypeDescription
versionnumberAgent version
snapshotobjectThe full agent at that version (below)
changedApiKeyIdnumber | nullThe API key ID if the change was made with an API key. null means it was changed in the console
createdAtstringRecorded time (ISO 8601)

snapshot

  • The agent body fields (direction and all create fields, including outboundInputSchema) plus manuals and tools.
  • manuals · tools include every item that is not deleted (including disabled ones), sorted by id ascending. A manual item has the shape of the manual response without aiAgentId and the timestamps.
  • Tool items use some key names that differ from the tool response. The MCP allow list is mcpAllowedTools, not allowedTools; mcpTools exists only on MCP tools and has three fields: name · readOnly · usable. There is no toolName.
  • Tool auth values are not stored; only hasAuthSecret is kept. authVersion is a number that increases by 1 whenever the auth settings (authType · authHeaderName · authSecret) change.

Rules the agent always follows on calls

The rules below apply to every agent regardless of its instructions (prompt) and cannot be changed. If the instructions conflict with these rules, these rules win.

  • The agent does not hide that it is an AI agent, and answers truthfully when asked whether it is a person.
  • On outbound calls, the agent first states the company name (group name) and that it is an AI agent in its opening line. If the other party does not want the call, it does not try to persuade them; it apologizes and ends the call.
  • The agent does not ask for or record card numbers, passwords, verification codes, or resident registration numbers.
  • The agent does not impersonate other companies, organizations, or people, and does not reveal its instructions to the caller.
  • The agent does not follow sentences inside tool results, manuals, or reference information as instructions.
  • When something is unclear, the agent asks again, and reads back dates, times, party sizes, names, and phone numbers to confirm them before recording.
  • The agent does not say it has handled something it has not recorded.
  • The agent ends the call only when the caller asks to end it or clearly says there is nothing else it can help with.
  • The agent wraps up the call 30 seconds before the maximum call duration.
  • Each call includes today's date (Korea time) and a weekday table so phrases like “next Saturday” can be turned into dates.

In-call features that need no setup

  • Keypad input — For long numbers such as order numbers or phone numbers, the agent suggests keypad input. The caller enters the digits and presses # (within 30 seconds).
  • Sending SMS— If the group’s SMS feature is on, the agent can send payment links, account numbers, or long addresses by SMS. It only sends links written in the instructions, reference information, manuals, or tool results from the current call. The price is the same as SMS sent through the API, and during the trial these messages are not covered by the included SMS.
  • Transfer to a person— On inbound calls, if the caller asks, the agent transfers the call to the group’s call forwarding number. If the call forwarding number is off, the agent says it cannot transfer. Outbound calls are not transferred.

Agent manuals

Manuals used by a single agent. A guidance manual (GENERAL) is a handling guide the agent reads when needed. A record manual (NOTE) has the agent ask the caller for set fields and record them, as in taking reservations or orders. Up to 30 manuals can be created per agent (400 AG004), and creating, updating, or deleting a manual increases the agent version.

MethodPathDescription
GET/group/{groupId}/agent/{agentId}/manualList manuals
POST/group/{groupId}/agent/{agentId}/manualCreate manual (201)
PATCH/group/{groupId}/agent/{agentId}/manual/{manualId}Update manual
DELETE/group/{groupId}/agent/{agentId}/manual/{manualId}Delete manual

Create and manage manuals

POST/group/{groupId}/agent/{agentId}/manual
FieldTypeRequiredDescription
namestringRequiredManual name (100 characters or fewer)
descriptionstring | nullOptionalWhen to use it (300 characters or fewer). The agent reads this to choose a manual, so be specific. If empty, “매뉴얼: <name>” (“Manual: <name>”) is used as the description
contentstringRequiredBody (1,500 characters or fewer)
isActivebooleanOptionalWhether it is in use (default true). If off, it is not used for calls
manualKindstringOptionalGENERAL guidance (default) / NOTE record intake
noteFieldsobject[] | nullOptionalFor NOTE, the fields to record (up to 20). See record fields. For GENERAL, discarded without error and stored as null
noteHandoffEnabledbooleanOptionalFor NOTE, transfer to staff after intake (default false). Actually transfers only when the group's call forwarding number is on. For GENERAL, stored as false
json
Request
{
  "name": "Reservations",
  "description": "When the customer wants to make, change, or cancel a reservation",
  "content": "Reservations are accepted only for dates within 30 days from today. For groups over 12 people, offer to transfer to staff.",
  "manualKind": "NOTE",
  "noteFields": [
    { "key": "name", "label": "Name for the reservation", "type": "TEXT" },
    { "key": "date", "label": "Date", "type": "DATE" },
    { "key": "time", "label": "Time", "type": "TIME" },
    { "key": "partySize", "label": "Party size", "type": "NUMBER" },
    { "key": "seat", "label": "Seating", "type": "ENUM", "options": ["Hall", "Private room"], "required": false },
    { "key": "phone", "label": "Contact number", "type": "PHONE", "description": "Take a different number if the customer wants" }
  ],
  "noteHandoffEnabled": false
}
Response (201)
{
  "id": 12,
  "aiAgentId": 7,
  "name": "Reservations",
  "description": "When the customer wants to make, change, or cancel a reservation",
  "content": "Reservations are accepted only for dates within 30 days from today. ...",
  "manualKind": "NOTE",
  "noteFields": [
    { "key": "name", "label": "Name for the reservation", "type": "TEXT" },
    { "key": "date", "label": "Date", "type": "DATE" }
  ],
  "noteHandoffEnabled": false,
  "isActive": true,
  "createdAt": "2026-11-16T05:05:00.000Z",
  "updatedAt": "2026-11-16T05:05:00.000Z"
}

noteFields in the response returns the fields as sent (defaults are not filled in for omitted type · required). The example shows only some of the fields.

  • List (GET) returns an array of manual objects sorted by id ascending. Disabled manuals are included.
  • Update (PATCH) leaves fields you don’t send unchanged. Only description · noteFields can be cleared by sending null; sending null for other fields returns 400 GL002. Changing NOTE to GENERAL also clears noteFields. If no value changed, the version does not increase.
  • Delete (DELETE) returns result: null.
  • A missing manual returns 404 AG003; a missing agent returns 404 AG001.

Record fields

Each field in noteFields is defined with the fields below. You receive its value under this key in fields of the INTAKE webhook.

FieldTypeRequiredDescription
keystringRequiredLetters, digits, and underscores starting with a letter, 40 characters or fewer. Keep keys unique within the manual so the same key is not used twice
labelstringRequiredField name to confirm with the caller (80 characters or fewer)
typestringOptionalField type (default TEXT, table below)
requiredbooleanOptionalWhether it is required (default true)
descriptionstringOptionalTips for collecting it (200 characters or fewer)
optionsstring[]Required for ENUM onlyChoices (1–20, up to 40 characters each, no empty strings)
typeValue received
TEXTFree text
NUMBERNumber
BOOLEANYes / No
DATEYYYY-MM-DD. For future dates such as reservations or visits; dates that do not exist or are before today (Korea time) are not recorded, and the agent asks again. The weekday is added in the intake content (content)
TIMEHH:mm (24-hour). “9:30” is normalized to 09:30; other formats are not recorded
PHONE9–11 digits starting with 0. If empty, the number the caller is calling from is used
ENUMOne of options

How record intake works

  • Request types are NEW (new intake) · CHANGE (change) · CANCEL (cancellation).
  • Before saving, the agent reads the details back to the caller and gets confirmation.
  • A change or cancellation in the same call updates the earlier intake instead of adding a new one (same intakeId).
  • A CHANGE · CANCEL with no earlier intake in the same call is recorded as “a change or cancellation request for an earlier reservation.”
  • The INTAKE webhook is sent immediately on every save, change, or cancellation.

Number binding

When you bind an inbound (INBOUND) agent to a group phone number, that agent answers calls to that number. To use AI answering on a KAT Cloud number, an active (ACTIVE) inbound agent must be bound to it. A default AI agent does not answer unbound numbers in its place.

Number binding is used only for inbound (INBOUND) agents. Outbound (OUTBOUND) agents do not need a bound number; the caller number is chosen with callerChannelId in the AI outbound call request.
MethodPathDescription
GET/group/{groupId}/channelList group phone numbers
GET/group/{groupId}/agent/{agentId}/channelList numbers bound to the agent
PUT/group/{groupId}/agent/{agentId}/channelReplace the list of bound numbers
GET/group/{groupId}/channel

The group’s phone numbers. The main number comes first, then the rest by id ascending. The id here is used in channelIdList for number binding and in callerChannelId for AI outbound calls. This API also returns 403 AG002 for groups with the AI agent feature off.

json
Response
[
  { "id": 100, "phoneNumber": "07012345678", "displayName": "Main number", "isPrimary": true },
  { "id": 101, "phoneNumber": "07012345679", "displayName": null, "isPrimary": false }
]
FieldTypeDescription
idnumberNumber (channel) ID
phoneNumberstringPhone number
displayNamestring | nullDisplay name
isPrimarybooleanWhether it is the main number
GET/group/{groupId}/agent/{agentId}/channel

Numbers bound to the agent. The response has the same shape as above.

PUT/group/{groupId}/agent/{agentId}/channel

Replaces the whole list of bound numbers and returns the bound numbers after the change. Sending an empty array ([]) removes all bindings. Number binding does not increase the agent version.

FieldTypeRequiredDescription
channelIdListnumber[]RequiredNumber IDs to bind. Up to 100; the same ID twice returns 400 GL002
json
Request
{
  "channelIdList": [100, 101]
}

Binding rules

  • Only phone numbers in the same group can be bound (400 AG006).
  • Each number can have only one inbound agent bound (409 AG008). Disabled (DISABLED) agents count too. Remove the other agent’s binding first.
  • If the group’s handling mode for both business hours and after hours is ‘people only’, AI does not answer calls, so numbers cannot be bound (400 AG007). KAT groups created in the console are set up for AI to answer, so this usually does not occur. If you see this error, contact us.

When no agent can answer an inbound call

If the number has no active inbound agent (not bound, disabled, or deleted), or the agent cannot be loaded, a default AI is not used instead. If the group’s call forwarding numberis on, the call is forwarded to it; otherwise the caller hears “지금은 전화를 받을 수 없습니다. 잠시 후 다시 걸어 주세요.” (“We can’t take your call right now. Please call again later.”) and the call ends.

Tools (HTTP·MCP)

Attach tools so the agent can look things up or take actions in your systems during a call. For example, it can look up shipping status by order number or change a reservation. An HTTP tool is a single API; an MCP tool is a single MCP server (Streamable HTTP). Up to 10 tools in total can be created per agent (400 AG012), and creating, updating, or deleting a tool increases the agent version.

MethodPathDescription
GET/group/{groupId}/agent/{agentId}/toolList tools (id ascending, including disabled tools)
POST/group/{groupId}/agent/{agentId}/toolCreate tool (201)
PATCH/group/{groupId}/agent/{agentId}/tool/{toolId}Update tool
DELETE/group/{groupId}/agent/{agentId}/tool/{toolId}Delete tool (result: null)
POST/group/{groupId}/agent/{agentId}/tool/{toolId}/testTest call (200)
POST/group/{groupId}/agent/{agentId}/tool/{toolId}/refreshRe-fetch the MCP tool list (200)

Create and manage tools

POST/group/{groupId}/agent/{agentId}/tool
FieldTypeRequiredDescription
kindstringOptionalHTTP (default) / MCP. Cannot be changed after creation
namestringRequiredLowercase letters, digits, and underscores starting with a lowercase letter, 48 characters or fewer. An HTTP tool appears to the agent as ext_<name>. For MCP, this is the server alias, 16 characters or fewer, and each server tool appears as mcp_<name>_<tool>. Duplicates within one agent return 409 AG014
descriptionstringRequiredWhen to use it (1,000 characters or fewer). The agent reads this to choose a tool, so be specific
urlstringRequiredURL to call (500 characters or fewer). Must pass the URL checks below (AG011)
httpMethodstringOptionalHTTP: GET (default, arguments as query) / POST (arguments as JSON body)
inputSchemaobjectOptionalHTTP: JSON Schema of the arguments (argument schema rules below). If omitted, no arguments. If invalid, 400 AG013
inputBindingsobject | nullOptionalHTTP: fills some arguments with fixed values or outbound input values. See outbound input fields. If invalid, 400 AO005
authTypestringOptionalNONE (default) / BEARER → Authorization: Bearer <authSecret> / HEADER → <authHeaderName>: <authSecret>
authHeaderNamestring | nullFor HEADERAuth header name (letters, digits, and hyphens, 100 characters or fewer). The disallowed names below are rejected
authSecretstring | nullFor BEARER · HEADERAuth value (1,000 characters or fewer). Stored encrypted and never returned in responses
timeoutMsnumberOptionalTime to wait for a response (ms, 1000–8000). Default 5000
writebooleanOptionalHTTP: a tool that changes your data (canceling an order, changing a reservation, and so on). If on, the agent calls it only after reading the details back to the caller and getting confirmation (default false)
allowedToolsstring[] | nullOptionalMCP: names of server tools to expose to the agent (up to 50, 64 characters each). If empty (null), all usable tools
isActivebooleanOptionalIf off, not used for calls (default true)
json
Request
{
  "kind": "HTTP",
  "name": "order_status",
  "description": "Looks up the shipping status by order number. Use when the customer asks about delivery.",
  "url": "https://api.example.com/orders/status",
  "httpMethod": "GET",
  "inputSchema": {
    "type": "object",
    "properties": {
      "orderNo": { "type": "string", "description": "Order number (e.g. A-1024)" }
    },
    "required": ["orderNo"]
  },
  "authType": "BEARER",
  "authSecret": "sk_live_your_secret",
  "timeoutMs": 5000
}
Response (201)
{
  "id": 3,
  "inputBindings": null,
  "aiAgentId": 7,
  "kind": "HTTP",
  "name": "order_status",
  "toolName": "ext_order_status",
  "description": "Looks up the shipping status by order number. Use when the customer asks about delivery.",
  "url": "https://api.example.com/orders/status",
  "httpMethod": "GET",
  "inputSchema": { "type": "object", "properties": { "orderNo": { "type": "string", "description": "Order number (e.g. A-1024)" } }, "required": ["orderNo"] },
  "authType": "BEARER",
  "authHeaderName": null,
  "hasAuthSecret": true,
  "timeoutMs": 5000,
  "write": false,
  "allowedTools": null,
  "mcpTools": null,
  "isActive": true,
  "createdAt": "2026-11-16T05:20:00.000Z",
  "updatedAt": "2026-11-16T05:20:00.000Z"
}

Response fields

The request fields (except authSecret) plus the fields below.

FieldTypeDescription
idnumberTool ID (toolId)
aiAgentIdnumberAgent ID
toolNamestringName the agent sees. ext_<name> for HTTP, mcp_<name>_<tool> for MCP (literally)
hasAuthSecretbooleanWhether an auth value is stored
mcpToolsobject[] | nullMCP: the server tool list last fetched (see MCP servers). null for HTTP
createdAt · updatedAtstringCreation and update times (ISO 8601)

The fields below may be stored and returned differently from what you sent.

FieldResponse value
httpMethod · inputSchemanull for MCP tools, regardless of what was sent
writeAlways false for MCP tools (set per server tool by readOnlyHint)
allowedToolsnull for HTTP tools, regardless of what was sent
authHeaderNamenull unless authType is HEADER
hasAuthSecretfalse when authType is NONE, since the stored auth value is deleted

Argument schema rules

inputSchema and the agent’s outboundInputSchema follow the same rules. Violations return 400 AG013 for tools (errors[0].field is inputSchema, with the reason in reason) and 400 AO005 for outbound input fields.

  • The top level uses only the keys type ("object") · properties · required.
  • Each argument uses only type · description · enum · items · properties · required. Keys such as format · $ref · oneOf are not accepted.
  • type is one of string · number · integer · boolean · array · object.
  • Argument names are letters, digits, and underscores starting with a letter or underscore, 64 characters or fewer.
  • Up to 20 arguments per level and up to 3 levels deep.
  • description is up to 300 characters. enum is only for string, with 1–50 values of up to 100 characters each.
  • array requires items, and required may list only names in properties.

URL checks (AG011)

Checked on create and update, and on every call during a call. When calling, the host name is resolved again and only public addresses are connected to. Rejections return 400 AG011, with one of the reasons below in errors[0].reason (and message).

reasonMeaning
주소 형식이 아닙니다.Cannot be parsed as a URL
https 주소만 쓸 수 있습니다.Not https, such as http
주소에 사용자 정보를 넣을 수 없습니다.The URL contains credentials, as in https://user:pass@host
내부망·사설 주소로는 보낼 수 없습니다.At least one IP the host name resolves to is in a blocked range (below)
주소를 찾을 수 없습니다.The host name cannot be resolved

Blocked ranges: 0.0.0.0/8 · 10.0.0.0/8 · 100.64.0.0/10 · 127.0.0.0/8 · 169.254.0.0/16 · 172.16.0.0/12 · 192.0.0.0/24 · 192.0.2.0/24 · 192.168.0.0/16 · 198.18.0.0/15 · 198.51.100.0/24 · 203.0.113.0/24 · 224.0.0.0/4 · 240.0.0.0/4, IPv6 :: · ::1 · 64:ff9b::/96 · 100::/64 · 2001:db8::/32 · fc00::/7 · fe80::/10 · ff00::/8, and IPv6 addresses that embed these IPv4 ranges.

Tool checks rejected with 400 GL002

The checks below come back as an input validation error (400 GL002), not an AG code.

Caseerrors[0].fieldreason
MCP alias (name) is 17 characters or morenameMCP 서버 별칭은 16자까지입니다.
HEADER with no header name or a disallowed nameauthHeaderNameHEADER 인증에는 다른 헤더와 겹치지 않는 헤더 이름이 필요합니다.
BEARER · HEADER with no authSecretauthSecretBEARER 인증에는 authSecret 이 필요합니다.
allowedTools contains a tool name not on the server or not usable on callsallowedTools서버에 없거나 통화에 쓸 수 없는 도구입니다 (mcpTools 의 usable 을 보세요).
refresh on an HTTP tooltoolIdMCP 도구만 새로고칩니다.

Names that cannot be used as the auth header name (case-insensitive): Host · Content-Length · Content-Type · Transfer-Encoding · Connection · Accept · User-Agent · X-Zerocall-Call-Id · X-Zerocall-Agent-Id · X-Zerocall-Caller · Idempotency-Key.

Update (PATCH)

PATCH/group/{groupId}/agent/{agentId}/tool/{toolId}
  • Fields you don't send are left unchanged. If a value changed, the same checks as on create run again.
  • authHeaderName · authSecret · inputBindings · allowedTools can be cleared by sending null. allowedTools: null reverts to all usable tools.
  • Sending only authSecret as null while authType stays BEARER · HEADER returns 400 GL002. To remove auth, change authType to NONE.
  • kind cannot be sent (400 GL002). To switch between HTTP and MCP, create a new tool.
  • write applies only to HTTP tools, and allowedTools only to MCP tools.
  • For MCP tools, any change (even just the description) reconnects to the server and fetches the tool list. If the server does not respond, the update fails with 400 AG015.
  • A missing tool returns 404 AG010.

Requests your server receives

When the agent calls an HTTP tool, a request like the one below goes to the registered URL. GET sends arguments as a query string; object and array values are converted to JSON strings, and arguments that are null are omitted. POST sends a JSON body, and sends {} even with no arguments. Optional arguments the agent fills with null are not sent.

http
GET /orders/status?orderNo=A-1024 HTTP/1.1
Host: api.example.com
Accept: application/json
User-Agent: ZeroCall-AI-Agent
Authorization: Bearer sk_live_your_secret
X-Zerocall-Call-Id: 8f3f8fd9-7ab8-4a26-b523-4f8eb7d38b85
X-Zerocall-Agent-Id: 7
X-Zerocall-Caller: 01012345678
Idempotency-Key: 9c2d1e7f0a4b8c3d6e5f1a2b3c4d5e6f7a8b9c0d

Request headers

HeaderWhenValue
AcceptAlwaysapplication/json
User-AgentAlwaysZeroCall-AI-Agent
X-Zerocall-Agent-IdAlwaysAgent ID
X-Zerocall-Call-IdDuring a callCall history ID (callHistoryId). Can be matched with call history and CALL_COMPLETED
X-Zerocall-CallerWhen the caller number is availableCaller phone number. Use it to check that the order belongs to the caller. Absent on calls with a hidden caller ID
Idempotency-KeyEvery call made during a call40 characters built from the call ID + the tool name the agent sees + the arguments. Also attached to lookup tools; calling again with the same arguments in the same call gives the same key
AuthorizationauthType BEARERBearer <authSecret>
<authHeaderName>authType HEADERauthSecret
Content-TypePOSTapplication/json
Tool requests do not carry the signature headers that webhooks do. To verify that a request came from KAT Cloud, check the auth value registered with authType (BEARER · HEADER).

Response rules

  • Respond within timeoutMs.The agent does not say anything else until it receives the tool’s response, so a slow response leaves the call silent. If the time is exceeded, the request is cut off and treated as a failure.
  • The response body is read up to 32KB; anything beyond that is cut to the first 32KB as text. Return only the values you need as short JSON.
  • Redirects (3xx) are not followed.
  • The agent reads the body of a 2xx response (JSON recommended) and tells the caller.

What the agent says based on the result

ResultWhat the agent says
2xxResponds based on the response content
3xx · 4xx (including when an MCP tool responds with isError)Does not make up a result; responds according to the response content (for example, no reservation found). Put the reason in the body
5xx · timeout · connection failure · blocked URL · argument validation failureDoes not say it was handled; instead says it cannot handle the request right now, has left the request, and that staff will check and get back to the caller. The request is recorded as an item that needs follow-up

An argument validation failure means the agent called the tool with arguments that do not match inputSchema. In that case your server is not called. Clear argument descriptions (description) and enum values reduce this.

Write tools (write: true)

  • The agent calls your server only after reading the details back to the caller and getting a “yes.” No request is sent before confirmation.
  • The confirmed argument that marks confirmation is used only on the agent side and is not sent to your server.
  • A write request that already succeeded in the same call (same arguments) is not sent again. Still, use Idempotency-Key on your server to process the same request only once.
  • MCP server tools whose readOnlyHint is not true are called the same way.

MCP servers

Register a Streamable HTTP MCP server with kind: "MCP", and the agent uses the server’s tools during calls.

json
Request
{
  "kind": "MCP",
  "name": "shop",
  "description": "Order lookup and cancellation. Use when the customer asks about an order.",
  "url": "https://mcp.example.com/mcp",
  "authType": "BEARER",
  "authSecret": "sk_live_your_secret",
  "allowedTools": ["get_order", "cancel_order"]
}
Response (201, partial)
{
  "id": 4,
  "kind": "MCP",
  "name": "shop",
  "toolName": "mcp_shop_<tool>",
  "httpMethod": null,
  "inputSchema": null,
  "write": false,
  "allowedTools": ["get_order", "cancel_order"],
  "mcpTools": [
    { "name": "get_order", "toolName": "mcp_shop_get_order", "description": "Look up an order", "readOnly": true, "usable": true, "unusableReason": null },
    { "name": "cancel_order", "toolName": "mcp_shop_cancel_order", "description": "Cancel an order", "readOnly": false, "usable": true, "unusableReason": null }
  ]
}

Tool list

  • On create, tools/list is fetched and stored (up to 5 pages). If it cannot be fetched, you get 400 AG015 with the connection failure reason in errors[0].reason. It is not fetched again during calls, so call refreshwhen you change the server’s tools.
  • Only tools with usable: true that are in allowedTools (if set) are attached to calls. The description of the registered MCP tool is appended in parentheses after each tool description.
  • Only tools with readOnlyHint: true are treated as lookup tools; the rest are called like write tools, after reading back and getting confirmation.
FieldTypeDescription
namestringTool name on the server
toolNamestringName the agent sees. In mcp_<alias>_<tool name>, the tool name is lowercased, characters other than letters, digits, and underscores become _, and it is cut to 60 characters. If names collide on a call, a suffix such as _2 is added
descriptionstringTool description (up to 1,000 characters)
readOnlybooleantrue only when the server gives annotations.readOnlyHint: true
usablebooleanWhether it can be used on calls (see schema handling below)
unusableReasonstring | nullWhy it cannot be used

Argument schema handling

  • Tools with anyOf · oneOf · allOf · $ref · not · if · patternProperties are usable: false.
  • Other constraints such as format · minLength are dropped. A type listed together with null, like "type": ["string", "null"], is accepted without null; if there are two or more non-null types, the tool cannot be used.
  • If type is missing, it is inferred from the shape (object if properties is present, array if items is present, string if enum is present). enum is kept only when all values are strings.
  • If the reduced result exceeds the argument schema rules (20 arguments, 3 levels, and so on), it is usable: false. A tool without inputSchema is treated as having no arguments.

Connection during a call

  • The connection is opened on the first tool call of each call and closed when the call ends. If the connection fails, it is retried on the next call.
  • Headers sent are X-Zerocall-Agent-Id, X-Zerocall-Call-Id during a call, X-Zerocall-Caller when the caller number is available, and the auth header. Unlike HTTP tools, the Accept · User-Agent · Idempotency-Key headers are not sent.
  • The deduplication key is sent in params._meta["zerocall/idempotencyKey"] of tools/call. It is computed the same way as the HTTP tool Idempotency-Key.
  • For the result, structuredContent is used if present; otherwise the text parts of content are joined with line breaks (as an object if there is a single part that is JSON). Results over 32KB are cut.
  • A result with isError: true is handled like a 4xx from an HTTP tool, and connection failures and timeouts like a 5xx (what the agent says based on the result).
  • The time limit (timeoutMs), not following redirects, and URL checks are the same as for HTTP tools.

Test call and refresh

POST/group/{groupId}/agent/{agentId}/tool/{toolId}/test

Actually calls the tool with the registered URL and auth, and returns the status code, elapsed time, and the start of the response. For HTTP tools, write tools are also called for real without confirmation, so test against your test server. Failures are returned as an ok: false result, not an error response. The version does not increase.

FieldTypeRequiredDescription
argsobjectOptionalArguments the agent would send (default {}). Do not include arguments bound with inputBindings
callerPhoneNumberstringOptionalTest number to send as X-Zerocall-Caller (9–11 digits starting with 0)
outboundInputsobjectOptionalOutbound input values for testing OUTBOUND_INPUT bindings (same shape as inputs in an AI outbound call request)
  • For HTTP tools, arguments are checked before sending. CONSTANT bindings are filled with their fixed values and OUTBOUND_INPUT bindings with values from outboundInputs, then checked against inputSchema. If they do not match, your server is not called and the reason is returned in error.
  • Example reasons: inputs.orderNo: REQUIRED (required argument missing), inputs: UNREGISTERED_FIELD (argument not in the schema), inputs.orderNo: STRING_REQUIRED (wrong type), INPUT_TOO_LARGE (over 16KB), BOUND_INPUT_OVERRIDE (a bound argument was put in args), REQUIRED_BINDING_MISSING (a bound outbound input value is missing from outboundInputs).
  • Since this is not a call, X-Zerocall-Call-Id · Idempotency-Key are not sent, and X-Zerocall-Caller is sent only when callerPhoneNumber is provided.
  • For MCP tools, it connects to the server and only fetches tools/list (no tool is called, and the stored list is not changed). On success, status is 200 and bodyPreview contains a JSON string with name · readOnly · usable for each tool.
json
Request
{
  "args": { "orderNo": "A-1024" },
  "callerPhoneNumber": "01012345678"
}
Response
{
  "ok": true,
  "status": 200,
  "latencyMs": 182,
  "bodyPreview": "{\"orderNo\":\"A-1024\",\"status\":\"IN_TRANSIT\",\"eta\":\"2026-11-18\"}",
  "truncated": false,
  "error": null
}
Request: test bound arguments (the reservation_update tool above)
{
  "args": { "answer": "CONFIRM" },
  "outboundInputs": { "customerName": "Minji Kim", "reservationId": "R-2041" }
}

Response fields

FieldTypeDescription
okbooleanWhether the server responded with 2xx
statusnumber | nullStatus code from your server. null if the request could not be sent
latencyMsnumberElapsed time (ms)
bodyPreviewstring | nullStart of the response (up to 2,000 characters). JSON is converted back to a string
truncatedbooleanWhether the response exceeds 32KB and is also cut during calls
errorstring | nullReason for argument validation failure, timeout, blocked URL, or connection failure (for example, 5초 안에 응답이 없습니다. [no response within 5 seconds], 연결하지 못했습니다 (ECONNREFUSED). [could not connect])
POST/group/{groupId}/agent/{agentId}/tool/{toolId}/refresh

Re-fetches and stores the MCP server’s tools/list and returns the tool object. The agent version increases only when the list changed. If it cannot be fetched, you get 400 AG015. If a name in allowedTools is missing from the re-fetched list, you get 400 GL002, so fix allowedTools first. Calling it on an HTTP tool returns 400 GL002.

Webhooks

When an event occurs, such as an inbound message, a delivery result, a call ending, an intake, an AI outbound call, or a media stream event, KAT Cloud sends an HTTP POST request to the URL you registered. You register one URL per event type (eventType).

Webhooks belong to the account, not to an API key. Every key on the same account and the console Webhookspage see and change the same settings. Notifications go to the webhooks registered on the group's group owner accountand are signed with that account's secret (the account that signed up in the KAT console is the owner of that KAT group). If one account has several groups, notifications for all of them go to the same URL, so use data.groupId to tell them apart in events that include it.

Managing webhooks

MethodPathDescription
GET/webhookList registered webhooks
POST/webhookRegister a webhook (201)
PATCH/webhook/{webhookId}Change the URL
DELETE/webhook/{webhookId}Delete
POST/webhook/{webhookId}/testSend a test notification (201)
GET/webhook/secretGet the signing secret — see Signature verification
POST/webhook/secret/rotateRotate the signing secret — see Signature verification

List

GET/webhook

Returns the webhooks registered on the account, in the order they were created.

json
Response
[
  {
    "id": 1,
    "eventType": "MESSAGE_RECEIVED",
    "url": "https://example.com/webhook/message",
    "createdAt": "2026-11-15T09:00:00.000Z",
    "updatedAt": "2026-11-15T09:00:00.000Z"
  },
  {
    "id": 2,
    "eventType": "AI_OUTBOUND",
    "url": "https://example.com/webhook/outbound",
    "createdAt": "2026-11-16T01:00:00.000Z",
    "updatedAt": "2026-11-16T01:00:00.000Z"
  }
]

Register

POST/webhook
FieldTypeRequiredDescription
eventTypestringYesMESSAGE_RECEIVED · SEND_RESULT · CALL_RECEIVED · CALL_COMPLETED · INTAKE · AI_OUTBOUND · MEDIA_STREAM
urlstringYesURL that receives notifications (see the rules below)
json
Request
{
  "eventType": "AI_OUTBOUND",
  "url": "https://example.com/webhook/outbound"
}
Response
{
  "id": 2,
  "eventType": "AI_OUTBOUND",
  "url": "https://example.com/webhook/outbound",
  "createdAt": "2026-11-16T01:00:00.000Z",
  "updatedAt": "2026-11-16T01:00:00.000Z"
}

URL rules:

  • http:// and https:// URLs are accepted. Use https in production.
  • The domain must resolve to a public address. localhost and addresses that resolve to internal or private IPs are rejected.
  • You can't put user info such as user:pass@ in the URL. If you need authentication, use signature verification.
StatusCodeWhen
400GL002eventType is not in the list, url is not a valid URL, or an unknown field was sent
400PK008The URL can't be accepted. The reason is in message and errors[0].reason (e.g. 내부망·사설 주소로는 보낼 수 없습니다. — "cannot send to an internal or private address")
409PK006This account already has a webhook for the same eventType — change its URL with PATCH
json
Response 400
{
  "status": 400,
  "code": "PK008",
  "message": "내부망·사설 주소로는 보낼 수 없습니다.",
  "errors": [{ "field": "url", "reason": "내부망·사설 주소로는 보낼 수 없습니다." }]
}

Change URL · Delete

PATCH/webhook/{webhookId}
FieldTypeRequiredDescription
urlstringYesNew URL (same rules as registration)

The response has the same shape as the registration response. The event type can't be changed; delete the webhook and register a new one.

DELETE/webhook/{webhookId}

On deletion, result is null. Events that occur after deletion are not sent. If the ID does not exist or belongs to another account, the response is 404 PK005; if it is not a number, 400 GL002.

Test

POST/webhook/{webhookId}/test

Sends one test notification to the registered URL and returns the result. It is signed with the same secret as real notifications, gets a new eventId, and has "isTest": true at the top level of the body. Use it to check your signature verification. It is not redelivered.

  • MESSAGE_RECEIVED·SEND_RESULT·INTAKE send data with sample values (groupId is 0).
  • CALL_RECEIVED·CALL_COMPLETED·AI_OUTBOUND·MEDIA_STREAM send an empty object ({}) as data.
json
Request (KAT Cloud → your URL, sample test body)
{
  "eventId": "3e1f9a7c-2d4b-4c6e-8f0a-1b2c3d4e5f6a",
  "eventType": "AI_OUTBOUND",
  "timestamp": "2026-11-16T01:00:00.000Z",
  "data": {},
  "isTest": true
}
Response (success)
{
  "success": true,
  "statusCode": 200,
  "responseTime": 150
}
Response (your server answered with a non-2xx status)
{
  "success": false,
  "statusCode": 500,
  "responseTime": 87,
  "error": "Request failed with status code 500"
}
Response (URL can't be accepted)
{
  "success": false,
  "responseTime": 0,
  "error": "내부망·사설 주소로는 보낼 수 없습니다."
}
FieldTypeDescription
successbooleantrue if your server answered with 2xx within 10 seconds
statusCodenumberHTTP status your server answered with. Absent if no response was received
responseTimenumberElapsed time (ms)
errorstringFailure reason. Absent on success. If your server answered with JSON that has a message field, it is that value

Even if the test fails, this API returns the result as a success response (201). If the webhook ID does not exist, the response is 404 PK005.

Delivery and redelivery

Every notification is sent as a JSON body with the same envelope.

json
{
  "eventId": "0b6f2c1e-3a4d-4b5c-9d8e-7f6a5b4c3d2e",
  "eventType": "CALL_COMPLETED",
  "timestamp": "2026-11-16T06:00:00.000Z",
  "data": { }
}
FieldTypeDescription
eventIdstringUnique ID of one notification. Stays the same on redelivery
eventTypestringThe registered event type
timestampstringWhen this attempt was sent (ISO 8601). New value on every redelivery
dataobjectEvent-specific content (see the event list)
isTestbooleanPresent as true only in test notifications

Success and failure

  • Delivery succeeds when your server answers with 2xx within 10 seconds. A non-2xx status, more than 10 seconds, or a connection failure is a failure.
  • Redirects (3xx) are not followed and count as failures. Register the final URL.
  • If no webhook is registered for an event type when the event occurs, nothing is sent. Registering later does not deliver past events.

Redelivery rules

NotificationSent toAttemptsRedelivery timingeventId
MESSAGE_RECEIVED · SEND_RESULT · CALL_RECEIVED · CALL_COMPLETED · INTAKEWebhook registered for that eventTypeUp to 3About 5 seconds after a failure, then about 15 seconds after another failureUUID
AI_OUTBOUNDAI_OUTBOUND webhookUp to 3About 5 seconds after a failure, then about 10 seconds after another failureUUID
MEDIA_STREAM — stream outbound call statusstatusCallbackUrl in the outbound request → MEDIA_STREAM webhookUp to 3About 5 seconds after a failure, then about 10 seconds after another failureUUID
MEDIA_STREAM — stream inbound call statusstatusCallbackUrl in the incoming-call response → statusCallbackUrl in the number settings → MEDIA_STREAM webhookUp to 3Sent immediately; 2 seconds later after a failure, then 5 seconds later after another failure{callId}:{type}
MEDIA_STREAM — incoming call (media_stream.call.incoming)webhookUrl in the number settings1 (not redelivered)— (must answer within 5 seconds)UUID
The eventId stays the same on redelivery. A notification your server processed but answered too late (and so counted as failed) can arrive again, so use eventId to skip notifications you have already processed. For AI outbound call and media stream events, where the receiver must restore the order, use data.sequence.

Recommended handling

  • Record completion and answer 2xx only after processing finishes. If processing fails, answer 5xx to receive it again.
  • For long-running work, answer 2xx within 10 seconds once the job is safely in a durable queue, and retry later failures from the queue.
  • Use eventId to skip only completed notifications; process failed ones when they arrive again.
  • In production, manage concurrent processing and completion records together with DB unique keys, transactions, etc. Calls to external APIs need their own duplicate protection.
  • Verify the X-Webhook-Signature signature.

Signature verification

Every webhook request carries a signature header. Verifying it on your server confirms that the notification came from KAT Cloud and that the body was not altered. Media stream incoming-call and status webhooks work the same way.

http
POST /webhook HTTP/1.1
Content-Type: application/json
X-Webhook-Timestamp: 1794812400
X-Webhook-Signature: v1=5f2b0c9e8d7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c

{"eventId":"6c1f8e2a-4b3d-4a5c-9e7f-0a1b2c3d4e5f","eventType":"INTAKE",...}
HeaderDescription
X-Webhook-TimestampSigning time (Unix seconds)
X-Webhook-Signaturev1=<hex>. HMAC-SHA256(secret, "<X-Webhook-Timestamp>.<raw body>") as lowercase hex

Verification steps

  1. Take the body exactly as the received bytes, before parsing it as JSON. Parsing and re-serializing changes whitespace and order, and the signature will not match.
  2. Reject the request if X-Webhook-Timestamp differs from the current time by more than 5 minutes (a recommended value to prevent replay attacks).
  3. Compute HMAC-SHA256 of "<timestamp>.<raw body>" with the secret and prefix it with v1=. Use the secret string as is as the key, including whsec_.
  4. Compare it with X-Webhook-Signature using a constant-time comparison (Node crypto.timingSafeEqual, Python hmac.compare_digest), and reject with 401 if they differ.
  5. If it passes, use eventId to skip notifications you have already processed, then process it.

Get · Rotate the secret

The secret is a string of whsec_ followed by 64 hex characters, and there is one per account. All events and webhook URLs use the same value, and notifications are signed with the group owner account's secret.

GET/webhook/secret

Returns the secret. If none exists yet, one is created and returned.

json
Response
{
  "secret": "whsec_3f1c9a7e5b2d8c4f6a0e1b3d5c7a9f2e4b6d8a0c1e3f5a7b9d2c4e6f8a0b1c3d"
}
POST/webhook/secret/rotate

Issues a new secret (201, same response shape as above). The very next notification is signed with the new value, so verification with the old value fails.

After rotation, redelivered notifications are also signed with the new value. Notifications that arrive before your server has the new value fail verification, and once redelivery ends (up to 3 attempts, within about 20 seconds) they are not sent again. Apply the new value right after rotating, and while you roll it out, accept a notification if it matches either the new or the previous value. If the secret has leaked, rotate it immediately. The media stream WebSocket connection signature uses the same secret (WebSocket messages).

Node.js (Express)

javascript
const crypto = require('crypto');
const express = require('express');

const app = express();

// The value from GET /webhook/secret (starts with whsec_). Keep it in an environment variable, not in code.
const WEBHOOK_SECRET = process.env.KATCLOUD_WEBHOOK_SECRET;
const TOLERANCE_SECONDS = 5 * 60; // reject notifications more than 5 minutes off

// Single-process example. An in-memory Set does not guarantee deduplication across restarts, multiple servers or concurrent requests.
// In production, use e.g. a unique key on eventId and a DB transaction that ties your business change to the "done" record.
const processedEventIds = new Set();

function verifySignature(rawBody, timestamp, signature) {
  if (!Buffer.isBuffer(rawBody) || !timestamp || !signature) return false;

  const ts = Number(timestamp);
  const now = Math.floor(Date.now() / 1000);
  if (!Number.isInteger(ts) || Math.abs(now - ts) > TOLERANCE_SECONDS) return false;

  // v1=HMAC-SHA256(secret, "<timestamp>.<raw body>") — the secret is the full string including whsec_
  const expected =
    'v1=' +
    crypto
      .createHmac('sha256', WEBHOOK_SECRET)
      .update(`${timestamp}.`)
      .update(rawBody)
      .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// express.raw() instead of express.json() — the signature must be computed over the exact bytes received.
// Call-completed notifications can carry long conversations, so set a generous limit (default is 100kb).
app.post('/webhook', express.raw({ type: 'application/json', limit: '5mb' }), async (req, res) => {
  const ok = verifySignature(
    req.body,
    req.get('X-Webhook-Timestamp'),
    req.get('X-Webhook-Signature'),
  );
  if (!ok) return res.status(401).send('invalid signature');

  const event = JSON.parse(req.body.toString('utf8'));

  // A redelivered notification has the same eventId — if already processed, just return 200
  if (processedEventIds.has(event.eventId)) return res.status(200).send('OK');
  try {
    // Implement handleEvent from the event-routing example below. Failures must be thrown as exceptions.
    await handleEvent(event);
    processedEventIds.add(event.eventId); // mark as done only after processing actually succeeded
    return res.status(200).send('OK');
  } catch (error) {
    console.error('Webhook processing failed:', error);
    // No "done" mark is left, so a redelivery with the same eventId can be processed again.
    return res.status(500).send('processing failed');
  }
});

app.listen(3000);

Python (Flask)

python
import hashlib
import hmac
import json
import os
import time

from flask import Flask, request

app = Flask(__name__)

# The value from GET /webhook/secret (starts with whsec_). Keep it in an environment variable, not in code.
WEBHOOK_SECRET = os.environ['KATCLOUD_WEBHOOK_SECRET']
TOLERANCE_SECONDS = 5 * 60  # reject notifications more than 5 minutes off

# Single-process example. An in-memory set does not guarantee deduplication across restarts, multiple servers or concurrent requests.
# In production, use e.g. a unique key on eventId and a DB transaction that ties your business change to the "done" record.
processed_event_ids = set()


def verify_signature(raw_body, timestamp, signature):
    if not timestamp or not signature:
        return False
    try:
        ts = int(timestamp)
    except ValueError:
        return False
    if abs(time.time() - ts) > TOLERANCE_SECONDS:
        return False

    # v1=HMAC-SHA256(secret, "<timestamp>.<raw body>") — the secret is the full string including whsec_
    digest = hmac.new(
        WEBHOOK_SECRET.encode(),
        timestamp.encode() + b'.' + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(('v1=' + digest).encode(), signature.encode())


@app.post('/webhook')
def webhook():
    # Verify the exact bytes received, not request.get_json()
    raw_body = request.get_data()
    ok = verify_signature(
        raw_body,
        request.headers.get('X-Webhook-Timestamp'),
        request.headers.get('X-Webhook-Signature'),
    )
    if not ok:
        return 'invalid signature', 401

    event = json.loads(raw_body)

    # A redelivered notification has the same eventId — if already processed, just return 200
    if event['eventId'] in processed_event_ids:
        return 'OK', 200
    try:
        # Implement a synchronous function that returns only after your processing is finished. Raise an exception on failure.
        handle_event(event)
        processed_event_ids.add(event['eventId'])  # mark as done only after processing actually succeeded
        return 'OK', 200
    except Exception:
        app.logger.exception('Webhook processing failed')
        # No "done" mark is left, so a redelivery with the same eventId can be processed again.
        return 'processing failed', 500


if __name__ == '__main__':
    app.run(port=8000)

Event list

eventTypedata.typeWhenDetails
MESSAGE_RECEIVED—A customer sent a text message to a KAT numberMESSAGE_RECEIVED below
SEND_RESULT—The final delivery result arrived for a message the group sentSEND_RESULT below
CALL_RECEIVED—An AI agent transfers a call to the call forwarding numberCALL_RECEIVED below
CALL_COMPLETED—A call ended and transcript and summary processing finishedCALL_COMPLETED below
INTAKE—An AI agent saves, changes, or cancels a record-type intake (immediately, during the call)INTAKE
AI_OUTBOUNDai_outbound.call.endedOnce, when an AI outbound call ends (including unanswered calls)AI outbound webhook
AI_OUTBOUNDai_outbound.analysis.completedOnce, when the transcript and summary of a recorded AI outbound call are finishedAI outbound webhook
MEDIA_STREAMmedia_stream.call.incomingA call arrived at a stream inbound number. Sent only to webhookUrl in the number settings; your response decides whether to answerStream inbound calls
MEDIA_STREAMmedia_stream.call.ringingA stream outbound call is ringing (outbound only, and only when a ringing signal arrives)Status webhooks
MEDIA_STREAMmedia_stream.call.answeredA stream call was answeredStatus webhooks
MEDIA_STREAMmedia_stream.call.completedAn answered stream call endedStatus webhooks
MEDIA_STREAMmedia_stream.call.failedThe call ended without being answeredStatus webhooks

AI_OUTBOUND·MEDIA_STREAM are split by data.type within one eventType. data always contains type·sequence·schemaVersion·occurredAt (the incoming-call event has no sequence); the other fields are described at the linked sections. Answer 2xx to an unknown data.type and skip it.

MESSAGE_RECEIVED

Sent when a customer sends a text message to the group's KAT number.

json
{
  "eventId": "5d1c9a3e-2b7f-4e6a-8c0d-1f2e3a4b5c6d",
  "eventType": "MESSAGE_RECEIVED",
  "timestamp": "2026-11-16T01:30:01.000Z",
  "data": {
    "chatId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "chatRoomId": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
    "groupId": 789,
    "channelId": 100,
    "phoneNumber": "07012345678",
    "senderPhoneNumber": "01098765432",
    "content": "Hello, I'd like to ask about a reservation.",
    "imageList": [],
    "receivedAt": "2026-11-16T01:30:00.000Z"
  }
}
FieldTypeDescription
data.chatIdstringMessage ID (32 characters)
data.chatRoomIdstringChat room ID (30 characters)
data.groupIdnumberGroup ID
data.channelIdnumberID of the receiving number (channel)
data.phoneNumberstringKAT number that received the message
data.senderPhoneNumberstringCustomer number that sent it
data.contentstringMessage content
data.subjectstringSubject. The field is omitted if there is none
data.imageListstring[]MMS image URLs. Empty array if none
data.receivedAtstringReceived at (ISO 8601)
The URLs in imageList are temporary, created at send time, and expire after a while. To keep the images, download and store them as soon as you receive the notification.

SEND_RESULT

Sent when the carrier returns the final delivery result for a message the group sent. It covers not only messages sent through the API but also messages sent by AI agents or from the console. data.chatId is the same 32-character string that /message/send returned as result.

json
{
  "eventId": "a7e3f0b2-6c1d-4f8e-9a2b-3c4d5e6f7a8b",
  "eventType": "SEND_RESULT",
  "timestamp": "2026-11-16T01:30:05.000Z",
  "data": {
    "chatId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "chatRoomId": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
    "groupId": 789,
    "channelId": 100,
    "sendPhoneNumber": "07012345678",
    "recvPhoneNumber": "01098765432",
    "content": "Your reservation is confirmed.",
    "chatType": "SMS",
    "sendStatus": "SUCCESS",
    "resultStatus": "4100",
    "resultMessage": "전달",
    "sentAt": "2026-11-16T01:30:00.000Z"
  }
}
FieldTypeDescription
data.chatIdstringMessage ID (32 characters)
data.chatRoomIdstringChat room ID (30 characters)
data.groupIdnumberGroup ID
data.channelIdnumberID of the sending number (channel)
data.sendPhoneNumberstringSender number
data.recvPhoneNumberstringRecipient number
data.contentstringMessage content
data.chatTypestringSMS · LMS · MMS · RCS · KAKAO
data.sendStatusstringSUCCESS (KAT Cloud handed the request to the carrier) · FAILED (failed at the request stage)
data.resultStatusstringFinal result code from the carrier
data.resultMessagestringMeaning of the result code. "Unknown" if the code is not in the table
data.sentAtstringWhen the message was created (ISO 8601)

Determine final success from resultStatus: SMS 4100, LMS·MMS 6600, and Kakao 7000 mean delivered. The /message/send response only confirms the request was accepted; for other codes, see Delivery result codes.

CALL_RECEIVED

Sent when an AI agent transfers a call to the call forwarding number (staff handoff). Sent once per call. Turn on the call forwarding number on the console Numbers page or with the call forwarding API.

json
{
  "eventId": "c2b8d4f6-1a3e-4c5d-8e7f-9a0b1c2d3e4f",
  "eventType": "CALL_RECEIVED",
  "timestamp": "2026-11-16T02:40:00.000Z",
  "data": {
    "callHistoryId": "8f3f8fd9-7ab8-4a26-b523-4f8eb7d38b85",
    "groupId": 789,
    "groupName": "Gangnam Branch",
    "channelId": 100,
    "fromNumber": "01012345678",
    "fromName": "Hong Gildong",
    "toNumber": "07012345678",
    "handOffReason": "고객이 담당자 연결을 요청함",
    "receivedAt": "2026-11-16T02:40:00.000Z"
  }
}
FieldTypeDescription
data.callHistoryIdstringCall history ID
data.groupIdnumberGroup ID
data.groupNamestringGroup name
data.channelIdnumberID of the receiving number (channel)
data.fromNumberstringCaller number (customer)
data.fromNamestringCaller name (when in contacts)
data.toNumberstringKAT number that received the call
data.handOffReasonstringWhy the AI agent transferred the call. Omitted if it transferred without a reason
data.receivedAtstringTransferred at (ISO 8601)

CALL_COMPLETED

Sent when a call ends and transcript and summary processing is finished. Sent for both inbound calls and AI outbound calls. For calls handled by a custom AI agent, agent information and the list of record-type intakes are included.

json
{
  "eventId": "0b6f2c1e-3a4d-4b5c-9d8e-7f6a5b4c3d2e",
  "eventType": "CALL_COMPLETED",
  "timestamp": "2026-11-16T02:45:30.000Z",
  "data": {
    "callHistoryId": "8f3f8fd9-7ab8-4a26-b523-4f8eb7d38b85",
    "groupId": 789,
    "channelId": 100,
    "fromNumber": "01012345678",
    "toNumber": "07012345678",
    "isInbound": true,
    "status": "ANSWERED",
    "tag": "AI_TO_DIRECT",
    "duration": 96,
    "summary": "예약 변경 요청을 접수하고 변경 가능한 시간대를 안내함",
    "sttAI": [
      { "role": "agent", "text": "안녕하세요. 강남점입니다.", "timestamp": 1.2 }
    ],
    "sttDirect": [
      { "role": "customer", "text": "직원 연결 부탁드립니다.", "timestamp": 30.1 }
    ],
    "recordingUrl": "https://storage.example.com/recording-direct.wav",
    "recordings": {
      "ai": {
        "url": "https://storage.example.com/recording-ai.wav",
        "expiresAt": "2026-11-16T03:45:30.000Z",
        "contentLength": 1234567,
        "contentType": "audio/wav",
        "customer": {
          "url": "https://storage.example.com/recording-ai-customer.wav",
          "expiresAt": "2026-11-16T03:45:30.000Z",
          "contentLength": 617283,
          "contentType": "audio/wav"
        },
        "agent": {
          "url": "https://storage.example.com/recording-ai-agent.wav",
          "expiresAt": "2026-11-16T03:45:30.000Z",
          "contentLength": 617284,
          "contentType": "audio/wav"
        }
      },
      "direct": {
        "url": "https://storage.example.com/recording-direct.wav",
        "expiresAt": "2026-11-16T03:45:30.000Z",
        "contentLength": 2345678,
        "contentType": "audio/wav"
      }
    },
    "startedAt": "2026-11-16T02:40:00.000Z",
    "completedAt": "2026-11-16T02:45:29.000Z",
    "agentId": 7,
    "agentVersion": 2,
    "agentDirection": "INBOUND",
    "intakes": [
      {
        "intakeId": 53,
        "callHistoryId": "8f3f8fd9-7ab8-4a26-b523-4f8eb7d38b85",
        "groupId": 789,
        "manualId": 12,
        "manualTitle": "Reservation",
        "requestType": "CHANGE",
        "customerPhoneNumber": "01012345678",
        "fields": { "name": "Hong Gildong", "date": "2026-11-17", "time": "15:00", "partySize": null },
        "fieldLabels": { "name": "Name", "date": "Date", "time": "Time", "partySize": "Party size" },
        "content": "Name: Hong Gildong / Date: 2026-11-17(화) / Time: 15:00",
        "summary": "11월 17일 예약을 15시로 변경 요청",
        "updatedAt": "2026-11-16T02:40:40.000Z"
      }
    ]
  }
}
FieldTypeDescription
data.callHistoryIdstringCall history ID
data.groupIdnumberGroup ID
data.channelIdnumberID of the group's number (channel)
data.fromNumberstringCalling number
data.toNumberstringCalled number
data.isInboundbooleantrue for inbound calls, false for outbound calls (AI outbound calls, etc.)
data.statusstringANSWERED · MISSED · REJECTED · UNKNOWN
data.tagstringAI (AI only) · DIRECT (person only) · AI_TO_DIRECT (AI transferred to a person) · UNKNOWN
data.durationnumberCall duration (seconds)
data.summarystringCall summary. Present only for recorded calls
data.sttAIobject[]Transcript of the AI segment {role, text, timestamp (seconds, decimal)}. Present only for recorded calls
data.sttDirectobject[]Transcript of the person segment. Same shape as sttAI. Present only for recorded calls
data.recordingUrlstringRecording file URL. If there are both an AI segment and a person segment, this is the person segment recording. Use recordings to get each segment
data.recordingsobjectRecordings by segment. ai = AI segment, direct = person segment. Each has url · expiresAt · contentLength · contentType; if per-speaker recordings exist, they are in customer · agent with the same shape
data.startedAtstringCall start time (ISO 8601)
data.completedAtstringWhen call processing finished and the notification was created (ISO 8601). May differ from when the call hung up
data.agentIdnumberID of the custom AI agent that handled the call. Present only for custom agent calls
data.agentVersionnumberAgent version used for the call (can be found in the revision history)
data.agentDirectionstringAgent direction INBOUND · OUTBOUND
data.intakesobject[]Record-type intakes from this call. Each item has the same shape as the INTAKE event's data. The field is absent if there are no intakes
  • Recording URLs are temporary. Download and store them before each item's expiresAt(at most 1 hour). If recording links can't be created within 5 seconds, the notification is sent without recordingUrl·recordings. To get them later, query call history details.
  • intakes is read when the notification is sent, so it includes changes made after the call ended. To get intakes immediately during the call, use the INTAKE event.
  • For the result and billing status of AI outbound calls, see the AI_OUTBOUND event and the AI outbound call details.

INTAKE (intake results)

Sent immediately during the call each time an AI agent saves, changes, or cancels an intake with a record-type manual. Record-type intakes from the default AI agent (not a custom agent) are also sent, with requestType: "NEW".

json
{
  "eventId": "6c1f8e2a-4b3d-4a5c-9e7f-0a1b2c3d4e5f",
  "eventType": "INTAKE",
  "timestamp": "2026-11-16T06:00:00.000Z",
  "data": {
    "intakeId": 53,
    "callHistoryId": "5c4e2a1b-8d7f-4e3a-b2c1-0f9e8d7c6b5a",
    "groupId": 789,
    "manualId": 12,
    "manualTitle": "Reservation",
    "requestType": "NEW",
    "customerPhoneNumber": "01012345678",
    "fields": { "name": "Hong Gildong", "date": "2026-11-21", "time": "19:00", "partySize": 2 },
    "fieldLabels": { "name": "Name", "date": "Date", "time": "Time", "partySize": "Party size" },
    "content": "Name: Hong Gildong / Date: 2026-11-21(토) / Time: 19:00 / Party size: 2",
    "summary": "11월 21일 19시 2명 예약",
    "updatedAt": "2026-11-16T06:00:00.000Z"
  }
}
FieldTypeDescription
data.intakeIdnumberIntake ID. If this intake is changed or canceled in the same call, it arrives again with the same ID
data.callHistoryIdstringCall history ID
data.groupIdnumberGroup ID
data.manualIdnumber | nullID of the manual used for the intake (null if none)
data.manualTitlestringManual name
data.requestTypestringNEW new intake · CHANGE change · CANCEL cancellation. CHANGE·CANCEL with an intakeId you have not seen before is a request to change or cancel an earlier reservation
data.customerPhoneNumberstringCustomer phone number
data.fieldsobjectField key → value. Read it by the keys in the manual's noteFields. Fields not collected are null
data.fieldLabelsobjectField key → field name (label)
data.contentstringIntake content (human-readable text; dates include the weekday)
data.summarystringOne-line summary
data.updatedAtstringWhen the intake was made or last changed (ISO 8601)
When the same intake changes, a new notification (new eventId) arrives with the same intakeId. Deduplicate by eventId, and store intakes by overwriting on intakeId.

KAT MCP server

An MCP server that lets AI agents such as Claude Code, Cursor, and VS Code use KAT Cloud as tools. It works with the same keys, the same permissions, and the same pricing as the REST API. For your own MCP server that an AI agent calls during a call, see Tools › MCP servers.

Connect

ItemValue
URLhttps://studio-gateway.zerocall.kr/mcp
TransportStreamable HTTP. No sessions; the response is a single JSON message (not SSE)
Authenticationx-api-key header (same key as REST). OAuth and the Authorization header are not accepted
MethodsPOST only (GET and DELETE return 405)
Server namekat-ai-outbound 1.1.0, tools only
Rate limitAll of /mcp counts as one limit: 1,200 requests per 60 seconds per key
The KAT Cloud API returns 403 GL011when called from an IP outside Korea. Clients running on your PC or on a server in Korea (Claude Code, Cursor, VS Code, Claude Desktop) connect from that machine's IP, so they work. Web connectors that connect on your behalf from a cloud outside Korea, and clients that can't add headers and support only OAuth, can't connect.

Claude Code

bash
claude mcp add --transport http kat https://studio-gateway.zerocall.kr/mcp \
  --header "x-api-key: $KAT_API_KEY"

Cursor (~/.cursor/mcp.json)

json
{
  "mcpServers": {
    "kat": {
      "url": "https://studio-gateway.zerocall.kr/mcp",
      "headers": { "x-api-key": "zpa.123.your-key-here" }
    }
  }
}

VS Code (.vscode/mcp.json)

json
{
  "inputs": [
    { "type": "promptString", "id": "kat-key", "description": "KAT API key", "password": true }
  ],
  "servers": {
    "kat": {
      "type": "http",
      "url": "https://studio-gateway.zerocall.kr/mcp",
      "headers": { "x-api-key": "${input:kat-key}" }
    }
  }
}

Claude Desktop (claude_desktop_config.json)

json
{
  "mcpServers": {
    "kat": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://studio-gateway.zerocall.kr/mcp", "--header", "x-api-key:${KAT_API_KEY}"],
      "env": { "KAT_API_KEY": "zpa.123.your-key-here" }
    }
  }
}

Don't commit keys to a repository; pass them through environment variables or an input prompt.

Tools

Every tool takes an optional groupId. A key created in the console has only one group, so you can omit it. Results come back as a JSON string in content[0].text, containing only the value that corresponds to result, without the REST { code, message, result } wrapper.

ToolWhat it doesEquivalent REST APIPricing
list_numbersGroup numbers and number IDs (main number first)GET /group/{groupId}/channel—
send_messageSend a message (SMS, LMS, MMS)POST /message/sendPaid
get_message_resultMessage delivery resultGET /message/send-result/{chatId}—
list_callsList call historyGET /call-history—
get_callOne call history record (transcript, summary, recording URL)GET /call-history/{callHistoryId}—
list_outbound_agentsOutbound AI agents and their input fieldsGET /group/{groupId}/agent?direction=OUTBOUND—
create_ai_outbound_callRequest an AI outbound callPOST /group/{groupId}/ai-outbound/callsPaid
get_ai_outbound_callAI outbound call status and resultGET …/ai-outbound/calls/{requestId}—
list_ai_outbound_callsList AI outbound calls (newest first)GET …/ai-outbound/calls—
terminate_ai_outbound_callCancel or hang up an AI outbound callPOST …/ai-outbound/calls/{requestId}/termination—
issue_numberAdd one more 070 number to the groupGET /group/{groupId}/numbers/quote · POST /group/{groupId}/numbersPaid

issue_number

Adds one more number to the key's group under the same conditions as the Add numbers API (paid plan, 30 numbers per group, 3 per group per hour). Call it in two steps.

  • Called without confirmMonthlyFee, it doesn't add a number and returns only { issued: false, confirmRequired: true, numbers, addedMonthlyFee, blockedCode }.
  • After the user confirms the added monthly fee, call it again with the same idempotencyKey plus confirmMonthlyFee: true to add the number. The result is the same as REST.
FieldTypeRequiredDescription
idempotencyKeystringYesKey identifying one add-number request, 1–128 characters. Shares the same key space as the REST Idempotency-Key
confirmMonthlyFeebooleanNotrue once the user has confirmed the added monthly fee
groupIdnumberNoOmit if the key has only one group

send_message

FieldTypeRequiredDescription
fromPhoneNumberstringYesSender number. A number in this group (list_numbers)
toPhoneNumberstringYesRecipient number
contentstringYesBody, 1–2,000 characters. Long messages are sent as LMS
subjectstringNoLMS/MMS subject, 64 characters or fewer
imageListstring[]NoUp to 3 MMS image keys (from POST /message/media/upload)
idempotencyKeystringYes1–128 characters

The result is { "chatId": "…" }. Recipient number checks, opt-outs, and the trial message limit (KC012) work the same as in REST.

create_ai_outbound_call

The input is the Request a call body (agentId, callerChannelId, destination, inputs) plus idempotencyKey (required). It returns the request acceptance result immediately, so check the call result afterwards with get_ai_outbound_call. callerChannelId is the id from the list_numbers result.

list_calls · get_call

FieldTypeRequiredDescription
channelIdnumberNoFilter by number ID
phoneNumberstringNoPart of the other party's or your number
keywordstringNoSearch by summary content
updatedAfterstringNoISO 8601. Only records changed after this time, oldest first (don't use with offset)
offset · limitnumberNoDefaults 0 · 20 (limit 1–100)
includeTracksbooleanNoInclude per-speaker recording URLs
callHistoryIdstringYes (get_call only)Call history ID

Idempotency keys and errors

Tools that cost money (send_message, create_ai_outbound_call, issue_number) require idempotencyKey. When retrying after a network error, use the same key; for a new message or a new outbound call, use a new key (for example, a UUID).

  • Same key, same content: not sent again; the first result is returned.
  • Same key, different content: error (AO006 for AI outbound calls).
  • Keys for send_message and issue_number are remembered for 7 days. Failed runs are not remembered, so you can retry with the same key. AI outbound call and add-number keys share the same key space as REST.

Errors raised inside a tool come back as HTTP 200 with isError: true, and the text is "{code}: {message}". An invalid key or exceeded rate limit comes back not as JSON-RPC but as the same error body as REST (401, 429).

bash
curl -s https://studio-gateway.zerocall.kr/mcp \
  -H "x-api-key: $KAT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0", "id": 3, "method": "tools/call",
    "params": {
      "name": "send_message",
      "arguments": {
        "fromPhoneNumber": "07012345678",
        "toPhoneNumber": "01098765432",
        "content": "Your reservation is confirmed.",
        "idempotencyKey": "msg-2026-11-16-0001"
      }
    }
  }'
json
Response (success)
{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"{\"chatId\":\"7f3e…\"}"}]}}
Response (tool error). The message text is in Korean: "This KAT Cloud group's trial
// has ended or its service is suspended. Please check the status in the console."
{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"KC008: 체험이 끝났거나 이용이 멈춘 KAT Cloud 그룹입니다. 콘솔에서 상태를 확인해 주세요."}],"isError":true}}

The Accept header must include both application/json and text/event-stream (otherwise 406). MCP clients add it automatically.

Credit and usage

KAT Cloud charges are deducted from your account's prepaid credit. Register a card and top up on the Billing screen in the console. No credit is deducted during the trial. Once you are on a paid plan, the monthly fee is deducted at the start of each billing period, and usage fees beyond the included usage are deducted during the period, every few minutes, by the amount that has accrued.

MethodPathDescription
GET/payment/credit/summaryCredit balance and auto top-up settings (per account)
GET/payment/credit/historyCredit usage and top-up history (per account)
GET/payment/group/{groupId}/usageThe group's included usage and usage for the current period
Credit summary and history belong to the account that created the key, not to the group. Keys of groups whose trial has ended or whose service is suspended also get 403 KC008 from these APIs; in that case, check the Billing screen in the console.

Credit summary

GET/payment/credit/summary

Returns the current credit balance and auto top-up settings.

json
Response
{
  "creditBalance": 48500,
  "billingStatus": "ACTIVE",
  "autoRechargeThreshold": 10000,
  "autoRechargeAmount": 50000,
  "costMap": {
    "CALL": 0.55,
    "AI_CALL": 110,
    "SMS": 11,
    "LMS": 35,
    "MMS": 110,
    "RCS": null,
    "KAO": null,
    "MOK": 0
  },
  "billingAnchorAt": null
}
FieldTypeDescription
creditBalancenumberCredit balance (KRW). Can be negative if an auto top-up failed and the account is unpaid
billingStatusstringACTIVE · INACTIVE
autoRechargeThresholdnumberAuto top-up runs when the balance falls below this value (KRW)
autoRechargeAmountnumberAuto top-up amount (KRW)
costMapobjectUnit price table with uppercase keys (CALL · AI_CALL · SMS · LMS · MMS · RCS · KAO · MOK). Not used to calculate KAT Cloud charges
billingAnchorAtstring | nullBilling anchor time (ISO 8601). null if not set

For the KAT plan's included usage and the current period's usage fees, see the katcloud field in Included usage and usage.

Usage and top-up history

GET/payment/credit/history

Returns credit deductions and top-ups, grouped by period. All dates are in Korea time. The query range is up to 1 year.

Query parameters

FieldTypeRequiredDescription
startDatestringNoStart date (Korea time YYYY-MM-DD, from 00:00 that day). Default: 1 year before endDate
endDatestringNoEnd date (Korea time YYYY-MM-DD, through the end of that day). Default: today
typestringNoFilter by one history type (table below). UNKNOWN matches rows with an empty type
groupBystringNoGrouping unit: day · week · month. Default day. A week starts on Sunday
fillEmptyBucketsbooleanNoIf true, periods with no history are filled with 0. Default false
includeDetailsbooleanNoIf true, details contains row-level history. Default false
limitnumberNoNumber of details, 1–500. Default 100
offsetnumberNoNumber of details to skip. Default 0

If startDate is later than endDate or the range exceeds 1 year, the response is 400 G400 (message: Invalid date range. Ensure startDate < endDate. or Date range cannot exceed 1 year.).

json
Request
GET /payment/credit/history?startDate=2026-11-01&endDate=2026-11-30&includeDetails=true
Response
{
  "effectiveStartDate": "2026-11-01T00:00:00+09:00",
  "effectiveEndDate": "2026-12-01T00:00:00+09:00",
  "totalCount": 2,
  "totalAmount": 39000,
  "summary": [
    {
      "periodStart": "2026-11-16T00:00:00+09:00",
      "periodEnd": "2026-11-17T00:00:00+09:00",
      "count": 2,
      "totalAmount": 39000,
      "startBalance": 9500,
      "endBalance": 48500,
      "amountByType": {
        "USAGE_DEDUCT": 0,
        "PLAN_DEDUCT": -11000,
        "CAMPAIGN_USAGE": 0,
        "MANUAL_ADJUST": 0,
        "AUTO_RECHARGE": 50000,
        "AI_CALL_REFUND": 0,
        "STORAGE_FEE_DEDUCT": 0,
        "UNKNOWN": 0
      },
      "amountByUsageCategory": {
        "CALL": 0,
        "MESSAGE": 0,
        "PLAN": -11000,
        "AI_CALL": 0,
        "RECHARGE": 50000,
        "ADJUST": 0,
        "REFUND": 0,
        "STORAGE": 0,
        "UNKNOWN": 0
      }
    }
  ],
  "details": [
    {
      "id": 90412,
      "type": "PLAN_DEDUCT",
      "amount": -11000,
      "absAmount": 11000,
      "direction": "DEBIT",
      "sourceType": "PLAN_DEDUCT",
      "usageCategory": "PLAN",
      "balanceBefore": 59500,
      "balanceAfter": 48500,
      "chatId": null,
      "callHistoryId": null,
      "campaignId": null,
      "appliedPaymentHistoryId": null,
      "description": "KAT 월 요금 (개인) 26.11.16~26.12.16",
      "createdAt": "2026-11-16T00:05:12.000Z"
    },
    {
      "id": 90411,
      "type": "AUTO_RECHARGE",
      "amount": 50000,
      "absAmount": 50000,
      "direction": "CREDIT",
      "sourceType": "AUTO_RECHARGE",
      "usageCategory": "RECHARGE",
      "balanceBefore": 9500,
      "balanceAfter": 59500,
      "chatId": null,
      "callHistoryId": null,
      "campaignId": null,
      "appliedPaymentHistoryId": null,
      "description": "크레딧 충전",
      "createdAt": "2026-11-16T00:05:10.000Z"
    }
  ],
  "hasMoreDetails": false
}

Response fields

FieldTypeDescription
effectiveStartDatestringStart time actually applied (Korea time, inclusive)
effectiveEndDatestringEnd time actually applied (Korea time, exclusive — 00:00 on the day after endDate)
totalCountnumberNumber of history rows in the range
totalAmountnumberTotal amount in the range. Deductions are negative, top-ups are positive
summaryobject[]Totals per groupBy period. Most recent period first
summary[].periodStart · periodEndstringPeriod start (inclusive) and end (exclusive), Korea time
summary[].count · totalAmountnumberNumber of rows and total amount in the period
summary[].startBalance · endBalancenumberBalance before the period's first row and after its last row
summary[].amountByTypeobjectTotal amount per type
summary[].amountByUsageCategoryobjectTotal amount per usageCategory
detailsobject[]Row-level history, most recent first (only when includeDetails=true)
details[].type · sourceTypestringHistory type (both have the same value)
details[].amountnumberAmount. Negative for deductions, positive for top-ups
details[].absAmount · directionnumber · stringAbsolute amount; DEBIT (deducted) · CREDIT (added)
details[].balanceBefore · balanceAfternumberBalance before and after this row
details[].descriptionstring | nullReason, in Korean (for example, KAT monthly fee, or KAT usage fee with the billing period)
details[].createdAtstringTime (ISO 8601 UTC)
hasMoreDetailsbooleantrue if more rows exist after offset + limit

How KAT Cloud charges appear in the history

KAT Cloud does not deduct credit per call or message; it deducts per billing period. So KAT rows have empty callHistoryId and chatId, and AI outbound calls and media stream calls do not get rows of their own — they are rolled into that period's usage fee rows. Identify KAT charges by type and description. The description text is returned in Korean; English glosses are shown in parentheses below.

Whattypedescription example
Monthly fee (at period start)PLAN_DEDUCTKAT 월 요금 (개인) 26.11.16~26.12.16 (KAT monthly fee (Personal))
Number and line monthly feePLAN_DEDUCTKAT 번호·회선 월 요금 (…) 26.11.16~26.12.16 (KAT number and line monthly fee)
Plan upgrade differencePLAN_DEDUCTKAT 플랜 올리기 차액 (개인 → 비즈니스) … (KAT plan upgrade difference (Personal → Business))
Usage fees beyond included usage (multiple rows as usage accrues during the period)USAGE_DEDUCTKAT 사용료 26.11.16~26.12.16 (KAT usage fee)
Refund when an AI outbound call included in usage fees becomes waived (positive)MANUAL_ADJUSTKAT AI 발신 면제 환급 (요청 {requestId}) (KAT AI outbound waiver refund (request {requestId}))
Top-up (auto or manual)AUTO_RECHARGE크레딧 충전 (credit top-up)

type values

ValueMeaning
USAGE_DEDUCTUsage fee deduction
PLAN_DEDUCTPlan or monthly fee deduction
AUTO_RECHARGECredit top-up
MANUAL_ADJUSTAdjustment (refunded amounts, etc.)
AI_CALL_REFUNDAI call refund
CAMPAIGN_USAGECampaign (bulk SMS) usage
STORAGE_FEE_DEDUCTRecording storage fee
STT_USAGE_DEDUCTCall analysis fee
UNKNOWNtype filter only — rows with an empty type

usageCategory values

usageCategory is a classification based on the type and the call or message linked to the row: PLAN (plan or monthly fee), RECHARGE (top-up), ADJUST (adjustment), REFUND (refund), STORAGE (recording storage fee), STT (call analysis), CALL · AI_CALL (deductions linked to call history), MESSAGE (deductions linked to a message), UNKNOWN (anything else). Aggregate KAT charges by type, as in the table above.

Included usage and usage

GET/payment/group/{groupId}/usage

Returns the group's included usage and usage for the current period: the current billing period on a paid plan, otherwise the trial period. Usage is not a stored value; it is recounted from call and message records on every request.

FieldTypeRequiredDescription
groupIdnumberYesGroup ID (path). 403 PK004 if it is not the group bound to the key
json
Response (during trial)
{
  "groupId": 789,
  "plan": "PERSONAL",
  "startDate": "2026-11-12T09:00:00.000Z",
  "endDate": "2026-11-19T09:00:00.000Z",
  "initialCallSecond": 4200,
  "useCallSecond": 720,
  "remainingCallSecond": 3480,
  "billedCallSecond": 720,
  "initialCallMinute": 70,
  "useCallMinute": 12,
  "remainingCallMinute": 58,
  "initialMessageCount": 50,
  "useSmsCount": 8,
  "useLmsCount": 1,
  "useMmsCount": 0,
  "useTotalMessageCount": 9,
  "remainingMessageCount": 42,
  "initialAiCallCount": 0,
  "useAiCallCount": 0,
  "remainingAiCallCount": 0,
  "katcloud": {
    "status": "TRIAL",
    "plan": "PERSONAL",
    "included": { "outboundMinutes": 70, "inboundMinutes": 500, "sms": 50 },
    "usage": {
      "outboundMinutes": 12,
      "inboundMinutes": 95,
      "sms": 8,
      "lms": 1,
      "mms": 0,
      "aiAgentMinutesByModel": { "gemini-3.8-live": 88 },
      "transcriptionMinutes": 0,
      "summaryMinutes": 0
    },
    "usageCharged": 0
  }
}

katcloud fields

Values based on the KAT plan are in the katcloud field. It is always present for KAT groups.

FieldTypeDescription
katcloud.statusstringTRIAL (in trial) · TRIAL_ENDED (trial ended) · ACTIVE (on a paid plan) · UNPAID (unpaid) · SUSPENDED (suspended) · CANCELED (canceled)
katcloud.planstringPERSONAL · BUSINESS. The trial uses the Personal (PERSONAL) plan's included usage
katcloud.includedobjectIncluded usage. outboundMinutes · inboundMinutes in minutes, sms in messages (no included usage for LMS or MMS)
katcloud.usage.outboundMinutesnumberOutbound minutes (rounded up to 1 minute per call)
katcloud.usage.inboundMinutesnumberInbound minutes (rounded up to 1 minute per call)
katcloud.usage.sms · lms · mmsnumberMessages sent (excluding failed and canceled)
katcloud.usage.aiAgentMinutesByModelobjectMinutes handled by AI agents, per voice model name (rounded up to 1 minute per call)
katcloud.usage.transcriptionMinutesnumberTranscript minutes (call duration of recorded calls)
katcloud.usage.summaryMinutesnumberSummary minutes (call duration of recorded calls)
katcloud.usageChargednumberUsage fees already deducted from credit this period (KRW, including VAT). Updated every few minutes, so it can lag behind usage. 0 during the trial

Which fields each call type counts toward

CallOutbound/inbound minutesAI agent minutesTranscript and summary minutes
Call answered by an AI agentinboundMinutesCounted per modelCounted if recorded
Call transferred to a forwarding numberinboundMinutes + the transferred portion also in outboundMinutesAI-handled portion onlyCounted if recorded
AI outbound calloutboundMinutesCounted per modelCounted if recorded
Stream outboundoutboundMinutes00 (no transcript or summary is produced)
Stream inboundinboundMinutes0Counted if recorded
  • Call duration is counted from when the other party answers. A call is added to usage after it ends and its record is finalized.
  • AI outbound and stream outbound calls are added after they are confirmed as billable calls. Unanswered calls and calls waived because of a KAT Cloud issue (settlementStatus WAIVED) are not added. To see the settlement status of a single call, check settlementStatus in AI outbound call details.
  • During the trial, to know whether you can place more AI outbound or stream outbound calls, check whether the outbound call request returns 403 AO016.

Common fields

The common fields at the top are filled in the same shape as for other plans. For KAT groups, the call fields hold outbound usage, the message fields hold SMS, and the AI count fields are 0 (KAT Cloud counts AI in minutes). See the katcloud field for inbound minutes and AI minutes.

FieldTypeDescription
groupIdnumberGroup ID
planstringSame as katcloud.plan
startDate · endDatestringPeriod start and end (ISO 8601 UTC). Trial start and end during the trial
initialCallMinute · initialCallSecondnumberOutbound included usage (minutes · seconds)
useCallMinute · useCallSecond · billedCallSecondnumberOutbound usage (minutes, rounded up to 1 minute per call · the same in seconds)
remainingCallMinute · remainingCallSecondnumberRemaining outbound included usage (minutes · seconds, never below 0)
initialMessageCountnumberSMS included usage (messages)
useSmsCount · useLmsCount · useMmsCountnumberMessages sent
useTotalMessageCountnumberTotal messages sent
remainingMessageCountnumberRemaining SMS included usage (LMS and MMS have no included usage)
initialAiCallCount · useAiCallCount · remainingAiCallCountnumberAlways 0 for KAT groups

Errors

StatusCodeWhen
403PK004Not the group bound to the key, or groupId is not a number
404GR001No trial or billing period record for the group
403KC008Group whose trial has ended or whose service is suspended

Error handling

When a request fails, the API returns an HTTP status code and an error body. Branch on code. message is a human-readable description whose wording may change, so do not branch on it. Most messages are in Korean; the tables below quote them as sent and explain each code in English.

Common format and codes

Unlike success responses, error bodies are not wrapped in result.

FieldTypeDescription
statusnumberSame value as the HTTP status code
codestringError code. Use it to branch your handling
messagestringDescription. When errors is present, it is the same text as errors[0].reason
errors{ field, reason }[]Per-field reasons when input validation fails. Present only when set
detailsobjectAdditional information. Present only when set (for AO005 from AI outbound calls and media streams, the reason is in details.reason)
json
Response (400 input validation failed)
{
  "status": 400,
  "code": "GL002",
  "message": "필수 값입니다.",
  "errors": [{ "field": "toPhoneNumber", "reason": "필수 값입니다." }]
}
Response (400 AI outbound call input error)
{
  "status": 400,
  "code": "AO005",
  "message": "발신 입력 또는 제한 설정이 올바르지 않습니다.",
  "details": { "reason": "inputs.customerName: REQUIRED" }
}
Response (429 rate limit)
{
  "status": 429,
  "code": "G429",
  "message": "요청이 너무 많습니다. 잠시 후 다시 시도해 주세요."
}

Reading codes

  • Two letters + three digits (AU011, KC008, AO013 …): errors defined by the API. They are grouped in the tables below.
  • Starting with GL: errors common to all APIs.
  • G + HTTP status (G400, G404, G429 …): errors raised before the API handles the request, such as an unknown path or the rate limit. message may be in English.
  • The same code can mean different things in different APIs. Read a code together with the HTTP status and the API you called (see Message and chat errors).

HTTP status

StatusMeaningTypical codes
400The request is invalidGL002, G400, API-specific codes
401The key is missing or invalidAU011, AU012
402Insufficient creditCB001, GR016
403Rejected due to permissions or group statePK004, KC008, GR076, AO002, GL011
404Resource or path not foundAG001, AO015, CR001, G404
409Already exists or conflicts with an earlier requestAG008, AG014, AO006, PK006, KC102
413Request or file too largeGL003, G413
415Unsupported fileGL007
429Too many callsG429 (rate limit), AO013·AO014 (outbound call limits), KC103 (adding numbers limit)
500Server errorGL001, GL008
502·503Cannot be processed right nowKC035, CH002, AO009, AO020

Common error codes

CodeHTTPmessageWhen · What to do
GL001500내부 서버 오류입니다.Unexpected server error. Follow the retry table below
GL002400잘못된 요청입니다.Input validation failed, malformed JSON, a field not in the table, or a non-numeric path ID (groupId returns 403 PK004). message is usually replaced with errors[0].reason
GL003413요청 크기가 너무 큽니다.The body exceeds 100MB
GL011403국외 IP에서는 접속할 수 없습니다. 해외에서 이용해야 한다면 고객센터로 문의해 주세요.Called from an IP outside Korea. Call from a server with a Korean IP. If you need to use it from abroad, contact KAT Cloud
G400400(message set by the API)Rejected with a message the API set itself. May be in English
G404404요청한 경로를 찾을 수 없습니다.Unknown path or method
G413413File too largeThe uploaded file exceeds 10MB
G429429요청이 너무 많습니다. 잠시 후 다시 시도해 주세요.Exceeded the rate limit. Wait Retry-After (seconds), then send again

Input validation reasons

The errors[].reason of GL002is the API's own reason when it defines one; otherwise it is one of the texts below.

reasonMeaning
허용되지 않은 필드입니다.Sent a field that is not in the table
필수 값입니다.A required field is missing
빈 값이 허용되지 않습니다.Empty string, etc.
문자열이어야 합니다. / 숫자여야 합니다. / 정수여야 합니다.Wrong type
true/false 값이어야 합니다. / 배열이어야 합니다.Wrong type
허용되지 않은 값입니다.Not in the list of allowed values
날짜 형식이 아닙니다.Not an ISO 8601 date
숫자타입이 아닙니다.A path ID is not numeric
잘못된 요청입니다.Any other rule, such as length, range, or format

Errors you can retry

ErrorSafe to retryHow
G429YesAfter waiting Retry-After seconds. The request was blocked before processing, so you can resend any API request as is
GL001 · 5xx · connection failure · timeoutOnly reads (GET) and outbound calls sent with an Idempotency-KeyWhether the request was processed is unknown. AI outbound calls and stream outbound calls are not placed twice if you resend with the same Idempotency-Key. Requests without an idempotency key, such as sending a message or chat, may go out twice if resent immediately, so first check the conversation list to see whether it was sent
KC035YesFailed to generate the announcement audio. Try again shortly
AO013LaterAfter an in-progress outbound call ends, resend with the same Idempotency-Key
AO014LaterRetry the next day (Korean date)
AO012LaterRetry within the allowed outbound call hours
AO009 · AO020 · CH002After a short waitThe feature is unavailable right now. If it persists, contact KAT Cloud
Other 4xxNoThe same request returns the same error. Fix the request or settings, then send

Check the conversation list with GET /chat and the outbound call request list with GET /group/{groupId}/ai-outbound/calls.

Authentication and group errors

Codes returned by key authentication, group state checks, KAT Cloud group rules, and the group, webhook, and call history settings APIs. The message column is the text exactly as the server sends it.

CodeHTTPmessageWhen · What to do
AU011401API 키가 필요합니다.The x-api-key header is missing. The Authorization header is not read
AU012401유효하지 않거나 만료된 API 키입니다.The key is malformed, does not exist, or has expired or been revoked. Check the console API keys page
GR076403운영 정책에 따라 이용이 정지된 계정이에요. 고객센터로 문의해 주세요.The group was suspended by an operator. Contact KAT Cloud
PK004403해당 그룹에 대한 접근 권한이 없습니다.A groupId not bound to the key, a non-numeric path groupId, or another group's resource
KC008403체험이 끝났거나 이용이 멈춘 KAT Cloud 그룹입니다. 콘솔에서 상태를 확인해 주세요.The trial has ended or the group is paused (for example, unpaid). All APIs, including sending messages, are rejected. Check the console Billing page
KC006403KAT Cloud 번호는 콘솔에서 받습니다. Studio API로 그룹을 만들거나 지울 수 없습니다.POST /group, DELETE /group/{groupId}. To get more numbers, use the adding numbers API
KC101403유료 플랜을 쓰는 중일 때만 번호를 추가할 수 있습니다. 체험·미납·정지 중이면 KAT Cloud 콘솔에서 결제를 먼저 확인해 주세요.Adding numbers. The group is on a trial, unpaid, or suspended
KC102409직접 추가로는 그룹 번호를 30개까지 둘 수 있습니다. 더 필요하면 KAT Cloud 담당자에게 요청해 주세요.Adding numbers. The group already has 30 numbers
KC103429그룹 하나에 1시간에 번호 3개까지 추가할 수 있습니다. 잠시 뒤 다시 시도해 주세요.Adding numbers. This group has already added 3 numbers within the past hour (console, API and MCP combined)
KC007403KAT Cloud 그룹은 멤버를 두지 않습니다. 직원 연결은 콘솔의 넘길 번호로 설정해 주세요.Member APIs. Set the number for transferring to staff with the call forwarding number API or in the console
KC012403체험에 포함된 문자를 모두 사용했습니다.POST /message/send during a trial. Check included usage with Included usage and usage
KC013400휴대폰·지역번호·070 번호만 넘길 번호로 쓸 수 있습니다.PATCH /group/{groupId}/call-forward
GR007400착신전환 활성화 시 전화번호가 필요해요!Enabling the call forwarding number without a number to use
KC031400올릴 수 없는 음성 파일입니다. WAV 나 MP3 파일을 올려 주세요.Upload announcement audio. message may be replaced with a specific reason
KC032400안내 음성 파일을 먼저 올려 주세요.Audio file mode is selected but no file has been uploaded
KC033400안내 문구를 입력해 주세요.Text mode is selected but the text is empty
KC034400안내 멘트는 20초 이내여야 합니다.The announcement is longer than 20 seconds
KC035502안내 음성을 만들지 못했습니다. 잠시 후 다시 시도해 주세요.Failed to generate audio from the text. Try again shortly
KC036404아직 만들어진 안내 음성이 없습니다.Download announcement audio
KC037400안내 멘트 설정은 inbound·outbound 로 나눠 보내거나, 예전 방식(enabled·direction·messageType)으로 보내 주세요.Mixed the two formats of call-start announcement settings
PV001400전화번호 형식이 올바르지 않아요 (숫자 7~15자리, 하이픈·+82 허용)Delete by other party's number
PV002400그룹에 연결된 번호는 상대 번호로 지울 수 없어요Passed your own group number as the other party's number
PV004404통화 기록을 찾을 수 없어요Delete a single call history record
PV005400마스킹 시점은 12~36개월 사이 정수이거나 null(기본 3년) 이어야 해요Call history retention settings
PK005404존재하지 않는 Webhook 설정입니다.Update, delete, or test a webhook configuration
PK006409해당 이벤트 타입의 Webhook이 이미 존재합니다.Each event type can have only one webhook
PK008400이 주소로는 웹훅을 받을 수 없습니다.Not a public http or https URL. The specific reason is in message and errors[0].reason

AI outbound call and media stream errors

Codes returned by the AI outbound call and media stream APIs. A missing or wrongly typed body field is the common input validation error (400 GL002), and a request ID in the path that is not a UUID returns 400 G400.

CodeHTTPmessageWhen · What to do
AO001404접근할 수 있는 캣클라우드 그룹이 없습니다.Not a KAT Cloud group, or a deleted group. Usually does not occur with keys created in the console
AO002403AI 발신 이용 승인이 없거나 현재 발신을 사용할 수 없습니다.An operator has stopped outbound calls, the group is paused, or the group's AI outbound call or media stream feature is off. Also returned when creating or updating outbound AI agents. Check the status on the console AI outbound calls page
AO005400발신 입력 또는 제한 설정이 올바르지 않습니다.Invalid destination number format, Idempotency-Key format, inputs, stream URL, metadata, call duration, or cursor. The reason is in details.reason
AO006409같은 멱등 키에 다른 발신 요청을 사용할 수 없습니다.Sent a different body with the same Idempotency-Key. Use a new key for a new outbound call
AO007404사용할 수 있는 발신 상담원이 없습니다.The agentId does not exist, is not for outbound calls (OUTBOUND), or is not on (ACTIVE)
AO008409도구 인증 버전이 변경되거나 폐기되었습니다.An HTTP tool of the AI agent that requires authentication has no secret. Set the authSecret of the tool again
AO009503AI 발신 실행은 아직 공개되지 않았습니다.AI outbound calls are not being accepted right now. If it persists, contact KAT Cloud
AO010400그룹에서 사용할 수 있는 정상 개통 발신번호가 아닙니다.callerChannelId is not an active group number. Find IDs with GET /group/{groupId}/channel
AO011403차단 또는 수신거부한 번호로 발신할 수 없습니다.The number is blocked by the group or has opted out of calls from this caller number
AO012403AI 발신 허용 시간이 아닙니다.Outside the allowed outbound call hours (default 08:00–21:00 Korea time)
AO013429동시에 발신할 수 있는 통화 수를 초과했습니다.The concurrent outbound call limit is full. AI outbound calls and stream outbound calls count together
AO014429오늘 발신할 수 있는 통화 수를 초과했습니다.The daily outbound call limit (by Korean date) is used up. AI outbound calls and stream outbound calls count together
AO015404접근할 수 있는 발신 요청이 없습니다.Unknown request ID. Also returned when looking up an AI outbound call ID through a stream path
AO016403사용할 수 있는 체험 잔여량 또는 유료 구독이 없습니다.Less than 1 minute of trial outbound included usage remains and there is no paid plan. Check the console Billing page
AO020503미디어 스트림은 아직 공개되지 않았습니다.Media streams are not being accepted right now. If it persists, contact KAT Cloud
AO021404그룹에서 쓸 수 있는 KAT 번호가 아닙니다.The from number of a stream outbound call, or the number in inbound call settings, is not a KAT number in your group
Both are 429, but G429 is the rate limit and clears after waiting Retry-After, while AO013·AO014 are outbound call limits that may not clear right away even if you wait. Branch on code. Rejected outbound call requests are not stored, so resending later with the same Idempotency-Key is evaluated as a new request.

AI agent errors

Codes returned by the AI agent, manual, number connection, and tool APIs. AG011·AG013·AG015 put the rejection reason in errors[0].reason, and message is replaced with the same text.

json
Response (400 Bad Request)
{
  "status": 400,
  "code": "AG011",
  "message": "https 주소만 쓸 수 있습니다.",
  "errors": [{ "field": "url", "reason": "https 주소만 쓸 수 있습니다." }]
}
CodeHTTPmessageWhen · What to do
AG001404존재하지 않는 AI 상담원입니다.The AI agent does not exist, was deleted, or belongs to another group
AG002403이 그룹은 커스텀 AI 상담원을 쓸 수 없습니다. 제로콜에 사용 신청을 해 주세요.The group's AI agent feature is off. KAT groups are created with it on; if you see this, contact KAT Cloud
AG003404존재하지 않는 상담원 매뉴얼입니다.Update or delete a manual
AG004400상담원 하나에 매뉴얼은 30개까지 등록할 수 있습니다.Create a manual
AG006400이 그룹의 전화번호만 연결할 수 있습니다.Passed another group's number ID when connecting a number
AG007400이 그룹은 운영시간·운영시간 외 모두 사람만 전화를 받도록 되어 있어 AI 상담원이 받을 수 없습니다. 제로콜 웹에서 응대 모드를 AI 로 바꾼 뒤 연결해 주세요.Connecting a number to an inbound AI agent. KAT groups are created so that AI answers calls, so this usually does not occur. If you see it, contact KAT Cloud
AG008409이미 다른 받는 전화용 상담원이 연결된 번호가 있습니다. 그 상담원의 연결을 먼저 끊어 주세요.A number can be connected to only one inbound AI agent
AG009400그룹 하나에 AI 상담원은 20개까지 등록할 수 있습니다. 쓰지 않는 상담원을 지운 뒤 등록해 주세요.Create an AI agent
AG010404존재하지 않는 상담원 도구입니다.Update, delete, refresh, or test-call a tool
AG011400이 주소로는 도구를 등록할 수 없습니다.Not https, the URL contains user info, or it is an internal or private address. The reason is in errors[0].reason
AG012400상담원 하나에 도구는 10개까지 등록할 수 있습니다.HTTP and MCP tools are counted together
AG013400도구 인자(inputSchema)를 받을 수 없는 모양입니다.inputSchema does not follow the rules. The reason is in errors[0].reason
AG014409이 상담원에 같은 이름의 도구가 있습니다.Tool names must be unique within an AI agent
AG015400MCP 서버에서 도구 목록을 받지 못했습니다.Create, update, or refresh an MCP tool. The reason, such as URL, authentication, or timeout, is in errors[0].reason

When creating or managing outbound (OUTBOUND) AI agents, AO001·AO002 can also be returned, and AO005when outbound input fields or a tool's input mapping are invalid (AI outbound call errors). Tool configuration errors such as a reserved header name or a missing authentication secret return 400 GL002.

Message and chat errors

Codes returned by the chat room, chat, and message APIs.

CodeHTTPmessageWhen · What to do
CH001404존재하지 않는 채널이에요!Send message / create chat room: the sender number is not a number in your group
CH001404존재하지 않는 문자에요!Get send result: the chatId does not exist or is not a message sent through the API
CH002503문자 발송에 실패했어요!Send message: messages cannot be sent from this number right now. If it persists, contact KAT Cloud
CH003400수신거부된 번호입니다.The recipient has opted out
CH004400제목이 너무 깁니다. (최대 64바이트)subject exceeds 64 bytes (about 32 Korean characters)
CH005400잘못된 커서 형식이에요.Invalid cursor for GET /chat. Pass the value you received as is
CH007400차단된 단어나 링크가 포함되어 발송할 수 없습니다.The content contains a blocked word or link
CR001404존재하지 않는 채팅방이에요!The chat room does not exist or was left (deleted)
CR002400잘못된 커서 형식이에요.Invalid cursor for GET /chat-room
CB001402크레딧 잔액이 부족하거나 자동충전에 실패했습니다.Send chat. Check your credit on the console Billing page
GR016402크레딧 잔액 부족으로 서비스가 차단되었습니다. 충전 후 이용 가능합니다.Send message or chat. Check your credit on the console Billing page
KC012403체험에 포함된 문자를 모두 사용했습니다.See Authentication and group errors
GL010403운영정책으로 인해 해당 기능이 제한되었습니다.Sending messages is blocked by operating policy. Contact KAT Cloud
GL007415지원하지 않는 파일유형입니다.A non-image file in a media upload
GL008500파일업로드에 실패했습니다.Chat media upload failed. Upload again
G400400업로드할 파일이 없습니다. / 업로드 가능한 파일이 없습니다.Message media upload has no file, or no file could be uploaded
G413413File too largeThe uploaded file exceeds 10MB
CH001means "sender number not found" when sending a message and "message not found" when getting a send result. Beyond that, CH003·CH004·CR001·CR002 are used with different meanings (and different HTTP statuses) in other APIs. Do not rely on the code alone; check the HTTP status and the API you called as well.

Message result codes

The final result of a message comes as a result code reported by the carrier. resultStatus is the code and resultMessage is its meaning. Both appear in the get send result response and the SEND_RESULT webhook. If no result has arrived yet, both fields are absent.

  • Success codes are 4100, 6600, 7000 (SMS, LMS·MMS, Kakao), and resultMessage is 전달.
  • To tell whether a message reached the recipient, check whether resultStatus is a success code, not sendStatus.
  • Codes not in the tables below have resultMessage set to Unknown. Decide by the code, not the meaning text.
  • The API returns resultMessagein Korean. The tables below show each code's meaning in English.

SMS result codes

resultStatusMeaning
4100Delivered
4400No signal (shadow area)
4401Handset powered off
4402Handset message storage full
4403Message deleted
4404No subscriber location information
4405Handset busy
4410Invalid number
4411NPDB error
4412Call rejected by recipient
4413SMSC format error
4414Not a subscriber, unassigned number, or service suspended
4415Identification code error
4420Other error
4421Timeout
4422Handset temporarily suspended
4423Handset rejected the message
4424Handset does not support URL SMS
4425Handset busy with a call
4426Retry limit exceeded
4427Other handset problem
4428System error
4430Spam
4431Sending restricted: recipient opted out (spam)
4432Callback number blocked (individual)
4433Callback number blocked (business)
4434Blocked: callback number not pre-registered
4435Blocked: callback number reported as spam to KISA
4436Callback number violates the pre-registration number rules
4437Duplicate sending restricted
4438Whitelist text check
4443Blocked as spam by KISA

LMS·MMS result codes

resultStatusMeaning
6600Delivered
6601Timeout
6602Handset busy with a call
6603No signal (shadow area)
6604Handset powered off
6605Handset message storage count exceeded
6606Invalid number
6607Service temporarily suspended
6608Other handset problem
6609Call rejected by recipient
6610Other error
6611Carrier SMC format error
6612Gateway format error
6613Handset does not support the service
6614Handset cannot take calls
6615Deleted by the SMC operator
6616Carrier message queue exceeded
6617Handled as spam by the carrier
6618Handled as spam by the Fair Trade Commission
6619Handled as spam by the gateway
6620Sending count exceeded
6621Message length exceeded
6622Invalid number format
6623Invalid data format
6624MMS information not found
6625NPDB error
6626Recipient opted out via 080 (SPAM)
6627Sending restricted: recipient opted out (SPAM)
6628Callback number blocked (individual)
6629Callback number blocked (business)
6630Number not in service
6631Blocked: callback number not pre-registered
6632Blocked: callback number reported as spam to KISA
6633Callback number violates the pre-registration number rules
6670Attachment size exceeded (60K)

Kakao result codes

Returned only for Kakao messages.

resultStatusMeaning
7000Delivered
7101Kakao format error
7103Invalid sender key (sender profile key)
7105Sender key (sender profile key) does not exist
7106Sender key (sender profile key) deleted
7107Sender key (sender profile key) blocked
7108KakaoTalk channel blocked (check in the KakaoTalk channel admin tool)
7109KakaoTalk channel closed (check in the KakaoTalk channel admin tool)
7110KakaoTalk channel deleted (check in the KakaoTalk channel admin tool)
7111KakaoTalk channel pending deletion (check in the KakaoTalk channel admin tool)
7112Invalid business registration number
7125KakaoTalk channel with messages blocked (check in the KakaoTalk channel admin tool)
7203FriendTalk recipient is not a friend
7204Template mismatch
7300Other error
7305Success uncertain (may be received within 30 days)
7306Kakao system error
7308Phone number error
7311Message does not exist
7314Message length exceeded
7315No template
7318Message cannot be sent
7322Sending not allowed at this time
7323Message group information not found
7324Message to resend does not exist
7325Variable length limit exceeded
7326Chat/bot switch button text length limit exceeded
7327Button/quick link content does not match the template
7328Emphasized title does not match the template
7329Emphasized title length limit exceeded (50 characters)
7330Message type does not match the template's emphasis type
7331Header does not match the template
7332Header length limit exceeded (16 characters)
7333Item highlight does not match the template
7334Item highlight title length limit exceeded (30 characters without image, 21 with image)
7335Item highlight description length limit exceeded (19 characters without image, 13 with image)
7336Item list does not match the template
7337Item description length limit exceeded in item list (23 characters)
7338Item summary does not match the template
7339Item summary description length limit exceeded (14 characters)
7340Item summary description contains disallowed characters (anything other than currency symbols/codes, digits, commas, decimal points and spaces)
7341Wide item list count does not match the min/max count
7342Main link does not match the template
7351Carousel item list count does not match the min/max count
7352Carousel item message too long
7421Timeout
7521Duplicate sending restricted

Code examples

Keep your key in an environment variable, not in code. The examples below assume the key is in KATCLOUD_API_KEY. Get the group ID (789 in the examples) from groupIdList of GET /auth-check or from GET /group.

cURL

bash
# Check the key — returns the group IDs bound to the key (groupIdList)
curl "https://studio-gateway.zerocall.kr/auth-check" \
  -H "x-api-key: $KATCLOUD_API_KEY"

# Send a message — result is the chatId
curl -X POST "https://studio-gateway.zerocall.kr/message/send" \
  -H "x-api-key: $KATCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromPhoneNumber": "07012345678",
    "toPhoneNumber": "01098765432",
    "content": "Hello. Your reservation is confirmed."
  }'

# Send result
curl "https://studio-gateway.zerocall.kr/message/send-result/<chatId>" \
  -H "x-api-key: $KATCLOUD_API_KEY"

# Call history (groupId required)
curl "https://studio-gateway.zerocall.kr/call-history?groupId=789&offset=0&limit=20" \
  -H "x-api-key: $KATCLOUD_API_KEY"

# AI outbound call — use the same Idempotency-Key when resending after a lost response
curl -X POST "https://studio-gateway.zerocall.kr/group/789/ai-outbound/calls" \
  -H "x-api-key: $KATCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20261116-0001" \
  -d '{
    "agentId": 11,
    "callerChannelId": 100,
    "destination": "01012345678",
    "inputs": { "customerName": "Gildong Hong" }
  }'

# On 429, use -i to read Retry-After (seconds), wait that long, then send again
curl -i "https://studio-gateway.zerocall.kr/group" \
  -H "x-api-key: $KATCLOUD_API_KEY"

Node.js

Requires Node.js 18 or later (built-in fetch). withRetry waits Retry-After on G429, and retries failures with an unknown outcome (connection failure, timeout, 5xx) only for requests that are safe to resend.

javascript
const API_BASE_URL = 'https://studio-gateway.zerocall.kr';
const API_KEY = process.env.KATCLOUD_API_KEY;

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// Returns only result on success; on failure throws an error carrying status and code
async function call(method, path, { body, headers } = {}) {
  const res = await fetch(API_BASE_URL + path, {
    method,
    headers: { 'x-api-key': API_KEY, 'Content-Type': 'application/json', ...headers },
    body: body === undefined ? undefined : JSON.stringify(body),
    signal: AbortSignal.timeout(15000),
  });
  const json = await res.json().catch(() => ({}));
  if (res.ok) return json.result;

  const error = new Error(json.message || 'HTTP ' + res.status);
  error.status = res.status;
  error.code = json.code; // 'G429', 'AO013', 'KC008' ...
  error.retryAfter = Number(res.headers.get('Retry-After')) || 60;
  throw error;
}

// safeToRepeat: requests that are never processed twice, such as reads (GET) or outbound calls sent with the same Idempotency-Key
async function withRetry(send, { safeToRepeat = false, maxAttempts = 5 } = {}) {
  for (let attempt = 1; ; attempt++) {
    try {
      return await send();
    } catch (error) {
      if (attempt >= maxAttempts) throw error;
      if (error.code === 'G429') {
        // Rate limit — the request was blocked before processing, so anything can be resent
        await sleep(error.retryAfter * 1000);
      } else if (safeToRepeat && (error.status === undefined || error.status >= 500)) {
        // Connection failure, timeout, 5xx — outcome unknown, so resend the same request as is
        await sleep(2 ** attempt * 1000);
      } else {
        throw error; // Handle business limits like AO013·AO014·KC012 and other 4xx separately by code
      }
    }
  }
}

// Send a message — no idempotency key, so retry only on G429. Result is the chatId
function sendMessage(from, to, content) {
  return withRetry(() =>
    call('POST', '/message/send', { body: { fromPhoneNumber: from, toPhoneNumber: to, content } }),
  );
}

// Call history — reads are safe to send any number of times
async function listCallHistories(groupId) {
  const result = await withRetry(
    () => call('GET', '/call-history?groupId=' + groupId + '&offset=0&limit=20'),
    { safeToRepeat: true },
  );
  return result.data;
}

// AI outbound call — one Idempotency-Key per outbound call. Derive it from your own ID, such as an
// order number, so the same value comes out even after the process restarts.
async function requestOutboundCall(groupId, order) {
  try {
    return await withRetry(
      () =>
        call('POST', '/group/' + groupId + '/ai-outbound/calls', {
          headers: { 'Idempotency-Key': 'order-' + order.id },
          body: {
            agentId: 11,
            callerChannelId: 100,
            destination: order.phoneNumber,
            inputs: { customerName: order.customerName },
          },
        }),
      { safeToRepeat: true },
    );
  } catch (error) {
    switch (error.code) {
      case 'AO012': // Outside the allowed outbound call hours
      case 'AO013': // No concurrent outbound call slot — after in-progress calls end
      case 'AO014': // Today's outbound call limit used up — the next day (Korean date)
        return scheduleLater(order, error.code); // Resend later with the same key
      default:
        throw error;
    }
  }
}

Python

python
import os
import time

import requests

API_BASE_URL = 'https://studio-gateway.zerocall.kr'
API_KEY = os.environ['KATCLOUD_API_KEY']


class ApiError(Exception):
    def __init__(self, status, body, retry_after):
        super().__init__(body.get('message', 'HTTP %d' % status))
        self.status = status
        self.code = body.get('code')  # 'G429', 'AO013', 'KC008' ...
        self.retry_after = retry_after


def call(method, path, body=None, headers=None):
    """Returns only result on success; raises ApiError on failure"""
    res = requests.request(
        method,
        API_BASE_URL + path,
        headers={'x-api-key': API_KEY, **(headers or {})},
        json=body,
        timeout=15,
    )
    try:
        data = res.json()
    except ValueError:
        data = {}
    if res.ok:
        return data.get('result')
    raise ApiError(res.status_code, data, int(res.headers.get('Retry-After', '60')))


def with_retry(send, safe_to_repeat=False, max_attempts=5):
    """safe_to_repeat: requests that are never processed twice, such as reads (GET) or outbound calls sent with the same Idempotency-Key"""
    for attempt in range(1, max_attempts + 1):
        try:
            return send()
        except ApiError as error:
            if attempt == max_attempts:
                raise
            if error.code == 'G429':
                time.sleep(error.retry_after)  # Rate limit — anything can be resent
            elif safe_to_repeat and error.status >= 500:
                time.sleep(2 ** attempt)
            else:
                raise  # Business limits like AO013·AO014·KC012 and other 4xx
        except requests.RequestException:
            # Connection failure or timeout — outcome unknown
            if not safe_to_repeat or attempt == max_attempts:
                raise
            time.sleep(2 ** attempt)


def send_message(from_number, to_number, content):
    """Send a message — no idempotency key, so retry only on G429. Result is the chatId"""
    return with_retry(lambda: call('POST', '/message/send', {
        'fromPhoneNumber': from_number,
        'toPhoneNumber': to_number,
        'content': content,
    }))


def request_outbound_call(group_id, order):
    """AI outbound call — one key per outbound call, the same value when resending"""
    headers = {'Idempotency-Key': 'order-%s' % order['id']}
    body = {
        'agentId': 11,
        'callerChannelId': 100,
        'destination': order['phone_number'],
        'inputs': {'customerName': order['customer_name']},
    }
    try:
        return with_retry(
            lambda: call('POST', '/group/%d/ai-outbound/calls' % group_id, body, headers),
            safe_to_repeat=True,
        )
    except ApiError as error:
        if error.code in ('AO012', 'AO013', 'AO014'):
            # Outside allowed hours · no concurrent slot · daily limit used up — resend later with the same key
            return schedule_later(order, error.code)
        raise

Routing webhook events (Node.js)

An example that fills in handleEvent from the signature verification example. For how to receive events and the fields of each event, see Event types, AI outbound call webhooks, and media stream status webhooks.

javascript
// Each business function must return when processing is done and propagate an exception on failure.
// The HTTP response and marking the eventId as done are handled by the receiving handler in the signature verification example.
async function handleEvent(event) {
  const { eventType, data } = event;

  switch (eventType) {
    case 'MESSAGE_RECEIVED':
      await handleIncomingMessage(data); // data.senderPhoneNumber, data.content
      break;
    case 'SEND_RESULT':
      // Whether it was delivered: check that data.resultStatus is a success code (4100·6600·7000)
      await handleSendResult(data);
      break;
    case 'CALL_RECEIVED':
      await handleCallReceived(data); // data.callHistoryId, data.fromNumber
      break;
    case 'CALL_COMPLETED':
      await handleCallCompleted(data); // data.callHistoryId, data.status, data.summary
      break;
    case 'INTAKE':
      await handleIntake(data); // Overwrite when the intakeId is the same
      break;
    case 'AI_OUTBOUND':
      // Order events within one outbound call request (data.requestId) by data.sequence
      if (data.type === 'ai_outbound.call.ended') {
        await handleOutboundEnded(data); // data.status, data.endReason, data.answered, data.callHistoryId
      } else if (data.type === 'ai_outbound.analysis.completed') {
        // Fetch the transcript and summary text from call history details using the callHistoryId from call.ended
        await handleOutboundAnalysis(data);
      }
      break;
    case 'MEDIA_STREAM':
      // data.type: media_stream.call.ringing · answered · completed · failed
      // Decide the call outcome by data.status · data.reason, not by the event name
      await handleStreamStatus(data); // data.callId, data.status, data.reason
      break;
    default:
      // Ignore unknown types (new events may be added)
      break;
  }
}