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.krRate limit
1,200 requests per 60 seconds, per key and per API| Item | Value |
|---|---|
| Authentication | x-api-key header |
| Body | application/json, UTF-8 (multipart/form-data for file uploads only) |
| Timestamps | ISO 8601 UTC, e.g. 2026-11-16T01:00:00.000Z (Korea time only for credit history dates and outbound calling hours) |
| Access location | Korean 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.
{
"code": "0",
"message": "Success",
"result": { "id": 789 }
}
{
"status": 403,
"code": "KC008",
"message": "체험이 끝났거나 이용이 멈춘 KAT Cloud 그룹입니다. 콘솔에서 상태를 확인해 주세요."
}
{
"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
| Method | Used by | Request | Response |
|---|---|---|---|
| offset | Call history, credit history | offset, limit | { data, total, offset, limit } |
| Cursor | Chat rooms, chats | cursor, size | { data, nextCursor, hasNext } |
| Cursor | AI outbound calls | cursor, 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 /groupto find yourgroupIdandchannelId. - 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).
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}.
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
/auth-checkChecks whether the key is valid and which group it is bound to.
{
"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
| HTTP | code | When |
|---|---|---|
| 401 | AU011 | No x-api-key header |
| 401 | AU012 | Invalid format, unknown key, or expired or revoked key (also returned if leading/trailing spaces or line breaks are included) |
| 403 | PK004 | The path contains a group ID the key is not bound to |
| 403 | KC008 | The group's trial has ended or its service is suspended |
| 403 | GR076 | Account suspended under the operating policy |
| 403 | GL011 | Called 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.
| Category | API | Condition |
|---|---|---|
| Messaging | /message/* · /chat-room · /chat | — |
| Call history | /call-history · /group/{groupId}/call-history/* · /group/{groupId}/call-record-privacy | — |
| Groups · announcements · usage | GET /group · GET|PATCH /group/{groupId} · /group/{groupId}/call-forward · /group/{groupId}/call-announcement · /payment/* | — |
| Adding numbers | /group/{groupId}/numbers · /group/{groupId}/numbers/quote | On 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}/channel | The 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/calls | Groups 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) |
| MCP | POST /mcp | Same conditions as above, per tool |
| Not available | POST /group · DELETE /group/{groupId} · member APIs | Creating 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.
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 by | Limit | Window |
|---|---|---|
| API key | 1,200 requests | 60 seconds |
| Requesting IP (including requests with a missing or invalid key) | 3,600 requests | 60 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.
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.
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.
| Method | Path | Description |
|---|---|---|
| GET | /group | List groups |
| GET | /group/{groupId} | Get group details |
| PATCH | /group/{groupId} | Change name, call recording, messaging tool |
| GET | /group/{groupId}/call-forward | Get call forwarding number |
| PATCH | /group/{groupId}/call-forward | Change call forwarding number |
List groups
/groupReturns the groups bound to the key as an array. A key created in the console returns your one KAT group.
[
{
"id": 789,
"title": "07012345678",
"phoneNumber": "07012345678",
"channelId": 100,
"status": "ACTIVE",
"createdAt": "2026-11-02T09:00:00.000Z",
"recordingEnabled": false
}
]| Field | Type | Description |
|---|---|---|
id | number | Group ID |
title | string | Group name (initially the 070 number) |
phoneNumber | string | The group's 070 number |
channelId | number | ID of that number |
status | string | ACTIVE = 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 |
createdAt | string | Creation time (ISO 8601) |
recordingEnabled | boolean | Whether 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
/group/{groupId}Returns the settings of one group. The fields used by KAT Cloud are listed in the table below.
{
"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
}| Field | Type | Description |
|---|---|---|
id | number | Group ID |
title | string | Group name |
phoneNumber | string | Main number |
status | string | Same as in List groups |
recordingEnabled | boolean | Whether calls are recorded |
useSMSTool | boolean | Whether the AI agent's send-message tool is enabled |
memberList | object[] | A KAT group contains only the one account that signed up |
createdAt | string | Creation 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
/group/{groupId}Only the fields you send are changed. KAT Cloud uses the three fields below.
| Field | Type | Required | Description |
|---|---|---|---|
title | string | No | Group name. 80 characters or fewer |
recordingEnabled | boolean | No | Turn call recording on or off. Same setting as Call recording on the console Numbers page |
useSMSTool | boolean | No | Lets 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 |
PATCH /group/789
{ "recordingEnabled": true }
{ "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.
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_RECEIVEDwebhook is sent when the call is forwarded. The reason the agent gave for the transfer is inhandOffReason.
Get
/group/{groupId}/call-forward{
"isCallForwardEnabled": true,
"callForwardNumber": "01012345678"
}| Field | Type | Description |
|---|---|---|
isCallForwardEnabled | boolean | Whether call forwarding is on |
callForwardNumber | string | null | Saved call forwarding number. The last number is kept even when forwarding is off |
Change
/group/{groupId}/call-forward| Field | Type | Required | Description |
|---|---|---|---|
isCallForwardEnabled | boolean | Yes | true to keep forwarding on |
callForwardNumber | string | No | Call 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 |
PATCH /group/789/call-forward
{ "isCallForwardEnabled": true, "callForwardNumber": "010-2345-6789" }
nullOnly 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.
isCallForwardEnabled: true). After changing it, check the value with the Get API.| Error | Meaning |
|---|---|
400 GL002 | Invalid number format (digits only, must be 8–12 digits starting with 0) |
400 KC013 | Not a mobile, area-code, or 070 number |
400 GR007 | Turning forwarding on, but there is no number to use |
403 PK004 · 404 GR001 | Another 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
/group/{groupId}/numbers/quoteDoesn't add a number. Shows only how much the monthly fee would increase with one more number, and what would block it right now.
{
"groupId": 789,
"numbers": 1,
"addedMonthlyFee": 1800,
"currency": "KRW",
"blockedCode": null
}| Field | Type | Description |
|---|---|---|
numbers | number | Number of numbers currently in the group |
addedMonthlyFee | number | Monthly fee increase for one more number (KRW, excluding VAT) |
blockedCode | string | null | Error code an add request would be rejected with right now (KC101, KC102, KC103, CH008, etc.). null if none |
Add a number
/group/{groupId}/numbersYou 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.
| Header | Required | Description |
|---|---|---|
Idempotency-Key | Yes | Your key identifying one add-number request, 1–128 characters |
| Field | Type | Required | Description |
|---|---|---|---|
confirmMonthlyFee | boolean | Yes | true once you have confirmed the added monthly fee. Any other value returns 400 |
POST /group/789/numbers
Idempotency-Key: number-20261116-0001
{ "confirmMonthlyFee": true }
{
"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 상담원을 연결해야 그 번호로 온 전화를 받습니다. 번호 요금은 다음 결제 기간부터 월 요금과 함께 빠집니다(일할 없음)."
}| Error | Meaning |
|---|---|
403 KC101 | Not currently on a paid plan (trial, overdue payment, or suspended) |
409 KC102 | The group already has 30 numbers |
429 KC103 | This API key has already added 3 numbers within the last hour |
429 CH008 | Exceeds the line limit per subscriber |
406 CH003 | No number available right now. Try again later or contact us |
409 | Different 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.
| Task | Console page |
|---|---|
| Get a 070 number | You 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/off | Numbers › Call forwarding number |
| Turn call recording on/off | Numbers › Call recording (also available via the API) |
| Connect your own SIP server (PBX, LiveKit, etc.) | SIP trunk |
| Create and revoke API keys | API keys |
| Cards, credits, plans | Billing |
| Cancel KAT | Account › Cancel KAT |
Check usage and remaining trial included usage with Included usage · usage.
Call-start announcement
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.
| Call | When · to whom |
|---|---|
| SIP trunk · inbound | To the caller, before a call to your 070 number is passed to your SIP server (SIP trunk) |
| SIP trunk · outbound | To the person who answered, right after they answer a call your SIP server placed through KAT Cloud |
| Media stream · inbound | To the caller, after KAT Cloud answers the call (Inbound stream) |
| Media stream · outbound | To 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.
| Method | Path | Description |
|---|---|---|
| GET | /group/{groupId}/call-announcement | Get settings |
| PUT | /group/{groupId}/call-announcement | Update settings |
| PUT | /group/{groupId}/call-announcement/audio | Upload an audio file (multipart) |
| DELETE | /group/{groupId}/call-announcement/audio | Delete the uploaded audio file |
| GET | /group/{groupId}/call-announcement/audio | Download the playback audio (WAV) |
Announcement types (messageType)
| Value | What 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_TEXT | Reads the text in customText aloud |
CUSTOM_AUDIO | Plays the audio file uploaded for that direction |
audioReady in the response to see whether the playback audio has been generated.Get settings
/group/{groupId}/call-announcementPer-direction settings are in inbound and outbound. Both have the same shape.
{
"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"
}| Field | Type | Description |
|---|---|---|
enabled | boolean | Whether the announcement plays in this direction |
messageType | string | Announcement type |
customText | string | null | Saved custom text |
spokenText | string | null | Text that is (or will be) played. null when an uploaded audio file is used |
hasCustomAudio | boolean | Whether an audio file has been uploaded for this direction |
customAudioDurationMs | number | null | Length of the uploaded audio file (milliseconds) |
audioReady | boolean | Whether playback audio for the current type has been generated |
audioUpdatedAt | string | null | When 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
/group/{groupId}/call-announcementSend 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.
| Field | Type | Required | Description |
|---|---|---|---|
inbound | object | No | Inbound call settings |
outbound | object | No | Outbound call settings |
inbound.enabled · outbound.enabled | boolean | No | Turn the announcement on or off |
inbound.messageType · outbound.messageType | string | No | Announcement type |
inbound.customText · outbound.customText | string | No | Text to read for CUSTOM_TEXT. 200 characters or fewer; leading and trailing whitespace is trimmed |
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_TEXTwith empty text returns400 KC033; choosingCUSTOM_AUDIOwith no file uploaded for that direction returns400 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.
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
/group/{groupId}/call-announcement/audioSend 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.
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
/group/{groupId}/call-announcement/audioDeletes 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)
/group/{groupId}/call-announcement/audioReturns 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).
curl -o announcement.wav \
-H "x-api-key: $KAT_API_KEY" \
"https://studio-gateway.zerocall.kr/group/789/call-announcement/audio?direction=OUTBOUND"Errors
| Code | HTTP | Meaning |
|---|---|---|
KC030 | 403 | Not a KAT Cloud group |
KC031 | 400 | Audio file can't be uploaded (format, sample rate, over 5 MB). The reason is in message |
KC032 | 400 | CUSTOM_AUDIO chosen but no file uploaded, or the upload request has no file |
KC033 | 400 | CUSTOM_TEXT chosen but the text is empty |
KC034 | 400 | Announcement longer than 20 seconds (both uploaded files and spoken text) |
KC035 | 502 | Couldn't generate or save the announcement audio. Try again later |
KC036 | 404 | No playback audio generated yet (download) |
KC037 | 400 | Nothing to change, per-direction and legacy formats mixed, or a required field missing in the legacy format |
G413 | 413 | Uploaded file is too large |
PK004 · GR001 | 403 · 404 | Another 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.
| Method | Path | Description |
|---|---|---|
| GET | /chat-room | List chat rooms |
| GET | /chat-room/{chatRoomId} | Get a chat room |
| POST | /chat-room | Open a chat room (returns the existing room if there is one) |
| DELETE | /chat-room/{chatRoomId} | Leave a chat room |
List chat rooms
/chat-roomPages 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.
| Field | Type | Required | Description |
|---|---|---|---|
groupId | number | Yes | Your group ID. 403 PK004 if outside the key's scope |
phoneNumber | string | No | Search by customer number (partial matches work) |
keyword | string | No | Search message content in the room. Matching messages are attached in matchedChatList |
cursor | string | No | nextCursor from the previous response. 400 CR002 if malformed |
size | number | No | 1–200, default 50 |
GET /chat-room?groupId=789&keyword=reservation&size=20
{
"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
| Field | Type | Description |
|---|---|---|
id | string | Chat room ID |
groupId · channelId | number | Group ID and channel (your number) ID |
channelType | string | Channel type. PHONE for KAT numbers |
channelPhoneNumber | string | Your number |
guestPhoneNumber | string | Customer number |
guestName | string | Only when the customer's name is known (otherwise the field is omitted) |
contactId · contactTitle | number · string | Only when the number is in the group's contacts |
lastMessageContent · lastMessageAt | string | Last message and its time. Messages sent through the API do not change these values |
sequence | number | Last sequence number of messages in the room |
operatorReadSequence · guestReadSequence | number | Read position of the operator and the customer |
isChannelRemoved | boolean | Whether your number was removed. If true, you cannot send to this room |
matchedChatList | object[] | Only when keyword is given. Pass an item's cursor as the cursor of GET /chat to see the messages around it |
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
/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
/chat-roomOpens 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).
| Field | Type | Required | Description |
|---|---|---|---|
channelId | number | Yes | Your number (channel) ID. Find it with GET /group |
phoneNumber | string | Yes | Customer number. Hyphens are removed before reading; must be 8–12 digits starting with 0 |
POST /chat-room
{
"channelId": 100,
"phoneNumber": "010-9876-5432"
}
"yyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"| HTTP | Code | When |
|---|---|---|
| 400 | GL002 | Invalid number format ("올바른 전화번호 형식이 아닙니다." — "Not a valid phone number format.") |
| 404 | CH001 | Channel does not exist or was removed |
| 403 | PK004 | Channel belongs to another group |
Leave a chat room
/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.
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
/chatReturns 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.
| Field | Type | Required | Description |
|---|---|---|---|
chatRoomId | string | Yes | Chat room ID. 404 CR001 if the room does not exist |
cursor | string | No | nextCursor or prevCursor from the previous response, or matchedChatList[].cursor from the chat room search. 400 CH005 if malformed |
cursorDate | string | No | Start from messages before this time (ISO 8601). Ignored when cursor is given |
size | number | No | 1–200, default 50 |
GET /chat?chatRoomId=yyyyyyyyyyyyyyyyyyyyyyyyyyyyyy&size=50
{
"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).
| Field | Type | Description |
|---|---|---|
id | string | Message ID (chatId) |
chatRoomId · channelId · groupId | string · number | Chat room, channel, and group the message belongs to |
sequence | number | Sequence number within the room |
content | string | Body |
subject | string | Subject (only when present) |
imageList | string[] | Image URLs. Temporary URLs generated when the response is built |
senderType | string | OPERATOR (operator or API send) · GUEST (customer) · AI (AI agent) · HQ (headquarters notice) |
senderUserId | number | Only for messages sent by an operator. Absent on messages sent through the API |
sendStatus | string | Send request result for outgoing messages. SUCCESS · FAILED · CANCELED (an operator canceled a failed message) |
resultStatus | string | Carrier result code. Filled in after the result arrives (result codes) |
chatType | string | SMS · LMS · MMS · RCS · KAO (KakaoTalk) · WEB |
timestamp | string | Creation 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
/chatSends 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.
| Field | Type | Required | Description |
|---|---|---|---|
chatRoomId | string | Yes | Chat room ID to send to |
content | string | Yes | Body |
subject | string | No | Subject. If set, the message goes as LMS or higher. 400 CH004 if over 64 bytes in EUC-KR (32 Korean characters) |
imageList | string[] | No | List of image keys. Use the values from the media upload response (300 characters or less each, no commas) |
externalMessageId | string | No | Your own message ID. It is only stored and returned; sending again with the same value sends again (no deduplication) |
Message type
| Type | Condition |
|---|---|
MMS | imageList contains at least one image |
SMS | No subject, and the body is 90 bytes or less in EUC-KR (Korean characters 2 bytes, English letters and digits 1 byte) |
LMS | Everything 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.
POST /chat
{
"chatRoomId": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
"content": "Your reservation has been changed to 3 PM.",
"externalMessageId": "ext-msg-001"
}
{
"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
| Field | Type | Description |
|---|---|---|
chatId | string | Message ID. Matches data.chatId in the SEND_RESULT webhook and the path value of Get send result |
chatRoomId · groupId · channelId | string · number | Chat room, group, and channel the message was sent from |
content · subject | string | Body and subject actually sent |
imageList | string[] | Image keys from the request (not URLs) |
externalMessageId | string | Value from the request |
sendPhoneNumber · recvPhoneNumber | string | Sender number · recipient number |
sendStatus | string | SUCCESS (handed to the carrier) · FAILED (could not be handed over) |
chatType | string | SMS · LMS · MMS |
resultStatus · resultMessage | string | Carrier result. Usually empty right after sending, so the fields are omitted |
createdAt | string | Creation 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
| HTTP | Code | When |
|---|---|---|
| 400 | GL002 | Invalid body (including missing fields and fields not in the table) |
| 400 | CH004 | Subject is over 64 bytes |
| 400 | CH007 | Contains a blocked word or link |
| 402 | CB001 | Insufficient credit balance, or auto top-up failed |
| 402 | GR016 | The group's message sending is blocked due to insufficient balance |
| 403 | GR076 | Group suspended under the operating policy |
| 403 | PK004 | Chat room belongs to another group |
| 404 | CR001 | Chat room does not exist or was left, or your number (channel) was removed so you cannot send |
Upload media
/chat/media/uploadUpload 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.
curl -X POST "https://studio-gateway.zerocall.kr/chat/media/upload" \
-H "x-api-key: $KAT_API_KEY" \
-F "files=@coupon.png"{
"urls": ["chat-media/456/1794812400000-k3j9x2.jpg"]
}| HTTP | Code | When |
|---|---|---|
| 400 | G400 | 4 or more files ("Too many files") |
| 413 | G413 | A single file is over 10MB ("File too large") |
| 415 | GL007 | Not an image, or an unsupported format |
| 500 | GL008 | Storage 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).
| Method | Path | Description |
|---|---|---|
| POST | /message/send | Send a message |
| GET | /message/send-result/{chatId} | Get send result |
| POST | /message/media/upload | Upload MMS images |
Send a message
/message/sendThe 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.
| Field | Type | Required | Description |
|---|---|---|---|
fromPhoneNumber | string | Yes | Your number to send from (a KAT number in your group). Hyphens are removed before reading. 404 CH001 if not a group number |
toPhoneNumber | string | Yes | Recipient number. Hyphens are removed before reading |
content | string | Yes | Body, 1–2,000 characters |
subject | string | No | Subject. 64 characters or less and 64 bytes or less in EUC-KR (32 Korean characters). 400 CH004 if over the byte limit |
imageList | string[] | No | List 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
| Type | Condition |
|---|---|
MMS | imageList contains at least one image |
SMS | No subject, and the body is 90 bytes or less in EUC-KR (Korean characters 2 bytes, English letters and digits 1 byte) |
LMS | Everything else (has a subject, or the body is over 90 bytes) |
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."
}
"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.
403 KC012 once it has used the messages included in the trial (50). Check what is left in Included usage · usage.Errors
| HTTP | Code | When |
|---|---|---|
| 400 | GL002 | Invalid body (including a missing or empty fromPhoneNumber) |
| 400 | CH003 | Recipient has opted out ("수신거부된 번호입니다." — "This number has opted out.") |
| 400 | CH004 | Subject is over 64 bytes |
| 400 | CH007 | Contains a blocked word or link |
| 402 | GR016 | The group's message sending is blocked due to insufficient balance |
| 403 | KC012 | All messages included in the trial are used up |
| 403 | KC008 | Trial has ended, or the group's service is paused |
| 403 | GR076 | Group suspended under the operating policy |
| 403 | GL010 | Message sending restricted under the operating policy |
| 404 | CH001 | fromPhoneNumber is not a number in your group ("존재하지 않는 채널이에요!" — "Channel does not exist!") |
| 503 | CH002 | That number (channel) cannot send messages right now |
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
/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!").
GET /message/send-result/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
{
"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"
}| Field | Type | Description |
|---|---|---|
id | string | Message ID (chatId) |
content · subject | string | Body and subject (subject is omitted if there is none) |
imageList | string[] | Image URLs (temporary URLs generated when the response is built) |
externalMessageId | string | externalMessageId given to POST /chat (only when present) |
fromPhoneNumber · toPhoneNumber | string | Sender number · recipient number |
sendStatus | string | SUCCESS · FAILED. Omitted if not yet determined |
chatType | string | SMS · LMS · MMS · RCS · KAO (in webhooks, KakaoTalk comes as KAKAO) |
resultStatus | string | Carrier result code. Omitted until the result arrives (result codes) |
resultMessage | string | Meaning of the result code (for example, 전달 = delivered). Unknown if the code is not in the table |
createdAt | string | Creation time |
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
/message/media/uploadPut 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.
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"{
"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.
| HTTP | Code | When |
|---|---|---|
| 400 | G400 | No files ("업로드할 파일이 없습니다." — "No files to upload."), none could be stored ("업로드 가능한 파일이 없습니다." — "No files could be uploaded."), 4 or more files ("Too many files") |
| 413 | G413 | A single file is over 10MB ("File too large") |
| 415 | GL007 | Not 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.
| Method | Path | Description |
|---|---|---|
| GET | /call-history | List call history |
| GET | /call-history/{callHistoryId} | Get a call history record |
| POST | /group/{groupId}/call-history/counterpart-erasure | Mask 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-privacy | Get or set when counterpart numbers are masked automatically |
List call history
/call-historyPages 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.
| Field | Type | Required | Description |
|---|---|---|---|
groupId | number | Yes | Your group ID. 403 PK004 if outside the key's scope |
channelId | number | No | Only calls on this number (channel). Empty list if it is not a number in the group |
phoneNumber | string | No | Search by calling or called number (partial matches work) |
keyword | string | No | Search summary content |
updatedAfter | string | No | Only records changed after this time (ISO 8601). When set, sorted by updatedAt ascending |
offset | number | No | 0 or greater, default 0 |
limit | number | No | 1–100, default 20 |
includeTracks | boolean | No | If true, attaches per-speaker files (customer · agent) to the recording. Default false |
GET /call-history?groupId=789&limit=20&includeTracks=true
{
"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.
| Field | Type | Description |
|---|---|---|
callHistoryId | string | Call history ID. The format differs by call type, so store it as a string as-is (table below) |
fromNumber · toNumber | string | Calling number · called number. Masked numbers look like 010****5678 |
isInbound | boolean | true for inbound calls, false for outbound calls |
callPhase | string | Call phase (table below). Use this value to determine the call outcome. Absent on older calls that have no phase record |
status | string | ANSWERED · MISSED · REJECTED · UNKNOWN (in progress). Kept for older integrations; outbound calls are ANSWERED even when not answered |
tag | string | AI (AI agent only) · DIRECT (staff only) · AI_TO_DIRECT (AI agent handed off to staff) · UNKNOWN |
duration | number | Actual connected time (seconds) |
summary | string | Summary. Present on recorded calls once summarization finishes |
sttAI · sttDirect | object[] | Transcript. AI agent segment · staff segment. Items are { role: agent | customer, text, timestamp (seconds) } |
recordingAI · recordingDirect | object | Recording files. AI agent segment (including stream calls) · staff segment (see Recording files below) |
isRecorded | boolean | Whether recording was on during the call. If false, there is no summary · stt · recording |
connection | string | STREAM for media stream calls. Otherwise the field is absent |
channelId · groupId | number | Your number (channel) and group used for the call |
createdAt | string | Call start time |
updatedAt | string | Time the record last changed. The basis for incremental sync |
callPhase
| Value | Meaning |
|---|---|
RECEIVED | Came in. Not yet connected, or choosing from the menu |
AI_TALKING | Talking with the AI agent |
QUEUED · RINGING · TALKING | Waiting for staff · ringing (for outbound calls, the counterpart's phone is ringing) · talking with staff |
ANSWERED | Answered call ended |
MISSED | No one answered (for outbound calls, the counterpart did not answer or the connection failed) |
ABANDONED | Caller hung up while waiting |
REJECTED | Rejected |
FAILED | Connection failed |
BLOCKED | Blocked 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
| Call | callHistoryId | Shape |
|---|---|---|
| Inbound call (AI agent · staff) | UUID format | isInbound true, fromNumber = customer, toNumber = your number |
| AI outbound call | ao + the outbound request ID with hyphens removed | Same 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 call | ao + the stream outbound callId with hyphens removed | Same shape as AI outbound calls, with connection: STREAM. The recording comes in recordingAI; no transcript or summary is created |
| Stream inbound call | Same value as callId in the status webhook | Same 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.
| Field | Type | Description |
|---|---|---|
url | string | Download URL (WAV) |
expiresAt | string | URL expiry time |
contentLength | number | File size (bytes) |
contentType | string | audio/wav |
customer · agent | object | Only 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 |
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
updatedAfterfor the next request to 1 second before theupdatedAtof 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
offsetat 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.
# 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 cycleGet a call history record
/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.
| Field | Type | Required | Description |
|---|---|---|---|
groupId | number | Yes | Your group ID (query) |
includeTracks | boolean | No | Whether to attach per-speaker recording files (query, default false) |
GET /call-history/ao6f1c2a0e1d2b4c3d9e8f0a1b2c3d4e5f?groupId=789If 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.
| Method | Number | Recording · transcript · summary | List · detail |
|---|---|---|---|
| Mask counterpart number (MASK) | Masked | Kept | Still returned (only the number is masked) |
| Erase counterpart number (DELETE) | Masked | Erased (including voicemail) | Not returned |
| Erase one call | Masked | Erased (including voicemail) | Not returned |
| Automatic masking setting | Masked N months after the call | Kept | Still 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
metadatais 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
cdrfield in the response gives the counts and the expiry date.
Mask or erase call history for a counterpart number
/group/{groupId}/call-history/counterpart-erasureFinds 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.
| Field | Type | Required | Description |
|---|---|---|---|
phoneNumber | string | Yes | Counterpart number, 30 characters or less. 010-1234-5678 · 01012345678 · +821012345678 · 821012345678 are treated as the same number. 400 PV001 if not 7–15 digits |
mode | string | Yes | MASK (mask the number only) or DELETE (mask the number, erase the recording, transcript, and summary, and remove from queries) |
dryRun | boolean | No | If 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.
POST /group/789/call-history/counterpart-erasure
{
"phoneNumber": "010-9876-5432",
"mode": "DELETE",
"dryRun": false
}
{
"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
}| Field | Type | Description |
|---|---|---|
matchedCalls | number | Number of target calls not yet processed at the time of the request |
processedCalls | number | Number of calls processed this time (0 for dryRun) |
remainingCalls | number | Number of calls remaining (equal to matchedCalls for dryRun). Send again until it reaches 0 |
recordingsPurged | number | Number of calls whose recording, transcript, and summary were erased (DELETE only) |
cdr.maskedNow | number | Number of call records older than 12 months masked this time (for dryRun, that would be masked) |
cdr.retained | number | Number of call records kept because they are under legal retention |
cdr.retainedUntil | string | null | Retention expiry date of the last kept call record (Korean date, YYYY-MM-DD). Masked automatically from the next day |
streamRequests | number | Number of stream outbound requests masked (for dryRun, that would be masked) |
Erase one call history record
/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.
DELETE /group/789/call-history/8f3f8fd9-7ab8-4a26-b523-4f8eb7d38b85
{
"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
/group/{groupId}/call-record-privacy/group/{groupId}/call-record-privacySets 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.
| Field | Type | Required | Description |
|---|---|---|---|
maskCounterpartAfterMonths | number | null | Yes | Integer 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 |
PUT /group/789/call-record-privacy
{
"maskCounterpartAfterMonths": 12
}
{
"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
| HTTP | Code | When |
|---|---|---|
| 400 | GL002 | Invalid body (invalid mode value, maskCounterpartAfterMonths missing or out of range, etc.) |
| 400 | PV001 | Invalid phone number format (7–15 digits; hyphens and +82 allowed) |
| 400 | PV002 | A number connected to your group was given as the counterpart number |
| 400 | PV005 | Automatic masking months is not an integer from 12 to 36 or null |
| 403 | PV003 | Not a KAT Cloud group |
| 403 | PK004 | Group outside the key's scope |
| 404 | PV004 | Call 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.
| Method | Path | Description |
|---|---|---|
| POST | /group/{groupId}/ai-outbound/calls | Create an outbound call request (202) |
| GET | /group/{groupId}/ai-outbound/calls | List outbound call requests |
| GET | /group/{groupId}/ai-outbound/calls/{requestId} | Get an outbound call request |
| POST | /group/{groupId}/ai-outbound/calls/{requestId}/termination | Hang 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.
| Item | Default | When exceeded |
|---|---|---|
| Calling hours | 08:00–21:00 Korea time (not allowed from 21:00 sharp) | 403 AO012 |
| Daily call count (by Korean calendar date) | 100 calls | 429 AO014 |
| Concurrent outbound calls | 1 call | 429 AO013 |
| Ring time | 30 seconds (NO_ANSWER if not answered) | — |
| Call duration | The AI agent's maximum call duration, or 480 seconds if not set | Hung up with MAX_DURATION |
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
/group/{groupId}/ai-outbound/callsThe 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).
| Header | Required | Description |
|---|---|---|
Idempotency-Key | Yes | Your key identifying one outbound call |
| Field | Type | Required | Description |
|---|---|---|---|
agentId | number | Yes | Outbound AI agent ID. Its direction must be OUTBOUND and it must be ACTIVE (otherwise 404 AO007) |
callerChannelId | number | Yes | ID of the group phone number (channel) to call from |
destination | string | Yes | Domestic (Korean) destination number, up to 32 characters |
inputs | object | Yes | Values 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.
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"
}
}
{
"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
/group/{groupId}/ai-outbound/calls/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.
| Query | Type | Description |
|---|---|---|
limit | number | 1–100, default 20 |
cursor | string | nextCursor from the previous response |
Response fields
| Field | Type | Description |
|---|---|---|
requestId | string | Outbound call request ID (UUID) |
agentId · agentVersion | number | AI agent and the version fixed at acceptance |
destination | string | Destination number (normalized) |
callerChannelId | number | Caller channel ID |
status | string | Status |
endReason | string | null | End reason |
reconciliation | string | PENDING = checking the dial result with the switch; otherwise NONE |
analysisStatus | string | NOT_APPLICABLE (not recorded or not connected) · PENDING · READY (transcript + summary) · PARTIAL (transcript only) · FAILED |
settlementStatus | string | PENDING · SETTLED · WAIVED (waived due to a failure on our side) |
finalAmount | number | null | 0 only for calls finalized at KRW 0 because they were not answered; null otherwise (see the credit history for amounts) |
answeredAt | string | null | Time the call was answered |
answerEstimated | boolean | true if the answer time was estimated from other records |
aiStartedAt | string | null | Time the AI agent's first audio went out |
terminationRequestedAt | string | null | Time the hang-up was requested |
callHistoryId | string | null | Call history ID. Fetch the recording, transcript, and summary with the call history API (null before dialing) |
Hang up
/group/{groupId}/ai-outbound/calls/{requestId}/terminationSend 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
terminationRequestedAtis set and returned. Hanging up takes a few seconds, so thestatusin 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
COMPLETEDand the reason isCUSTOMER_TERMINATED.
Statuses and end reasons
| status | Meaning |
|---|---|
ACCEPTED | Accepted. Ends with DISPATCH_EXPIRED if not dialed within 30 seconds |
DIALING | Being dialed by the switch |
RINGING | The callee's phone is ringing (only when the carrier sends a ringing signal; usually skipped on Korean lines) |
CONNECTED | Callee answered |
IN_PROGRESS | The AI agent's first audio went out |
COMPLETED | Ended after answer (also COMPLETED when ended by the hang-up API, maximum duration, or the AI agent) |
NO_ANSWER · BUSY · REJECTED | No answer · busy · rejected |
CANCELED | Canceled before answer by a hang-up request, an operator stop, or the AI agent ending the call |
FAILED | Failed. FAILED on a system error, even after answer |
| endReason | Meaning |
|---|---|
REMOTE_HANGUP | The callee hung up |
NO_ANSWER · BUSY · REJECTED | No answer (30-second ring) · busy · rejected |
CARRIER_FAILURE | Failure on the carrier network |
CUSTOMER_TERMINATED | Hang-up API (including hang-ups from the console) |
MAX_DURATION | Maximum call duration exceeded |
AGENT_ENDED | The AI agent ended the call |
SYSTEM_FAILURE | Error on the KAT Cloud side |
DISPATCH_EXPIRED | Not dialed within 30 seconds of acceptance |
ADMISSION_CHANGED | Failed a condition rechecked just before dialing (calling hours, limits, trial, etc.) |
ORIGINATE_REJECTED | The switch rejected the call |
GROUP_SUSPENDED | An operator stopped outbound calling for the group, canceling requests not yet dialed |
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.type | When |
|---|---|
ai_outbound.call.ended | Once, when the call ends (including unanswered calls) |
ai_outbound.analysis.completed | Once, when the transcript and summary of a recorded call are ready |
{
"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"
}
}
{
"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.
| Method | Path | Description |
|---|---|---|
| POST | /group/{groupId}/media-stream/calls | Place a stream outbound call (202) |
| GET | /group/{groupId}/media-stream/calls/{callId} | Stream outbound call status |
| POST | /group/{groupId}/media-stream/calls/{callId}/termination | Hang up a stream outbound call (202) |
| GET | /group/{groupId}/media-stream/inbound | List 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 |
Stream outbound
/group/{groupId}/media-stream/callsWhen 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.
| Field | Type | Required | Description |
|---|---|---|---|
from | string | Yes | Caller 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 |
to | string | Yes | Domestic (Korean) destination number |
streamUrl | string | Yes | WebSocket URL to connect to. wss:// only, up to 500 characters, must resolve to a public IP |
statusCallbackUrl | string | No | Status webhook URL for this call (http or https). If omitted, the MEDIA_STREAM webhook is used |
metadata | object | No | Up to 4,096 bytes. Passed as-is in customParameters of the start message and in status webhooks |
timeLimit | number | No | Maximum call duration after answer, in seconds. 10–14400, default 3600 |
codec | string | No | PCMU (default, μ-law) or PCMA (A-law) |
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
}
{
"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
/group/{groupId}/media-stream/calls/{callId}/group/{groupId}/media-stream/calls/{callId}/terminationThe 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.
| status | Meaning |
|---|---|
queued | Accepted (dialed within 30 seconds) |
initiated | Dialing |
ringing | Ringing signal received (usually skipped on Korean lines) |
in-progress | Callee answered |
completed | Ended after answer |
busy · no-answer · rejected · canceled | Ended without answer |
failed | Failed. 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
/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.
| Field | Type | Required | Description |
|---|---|---|---|
webhookUrl | string | Yes | URL to call when a call comes in (public http or https URL, up to 500 characters) |
statusCallbackUrl | string | No | Status webhook URL for calls to this number |
PUT /group/789/media-stream/inbound/070-1234-5678
{
"webhookUrl": "https://api.example.com/kat/incoming",
"statusCallbackUrl": "https://api.example.com/kat/status"
}
{
"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.
{
"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"
}
}
{
"action": "stream",
"streamUrl": "wss://voice.example.com/stream",
"statusCallbackUrl": "https://api.example.com/kat/status",
"metadata": { "lang": "ko" },
"codec": "PCMU"
}
{ "action": "reject", "reason": "busy" }| Response field | Rule |
|---|---|
action | stream or reject |
streamUrl | Required for stream. Same wss rules as stream outbound |
statusCallbackUrl | Optional. Takes precedence over the value in the number setting |
metadata | Optional object, up to 4,096 bytes. Sent as customParameters in start |
codec | Optional. PCMU (default) or PCMA |
reason | For 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.type | When | Additional fields |
|---|---|---|
media_stream.call.ringing | Outbound only, when a ringing signal is received | — |
media_stream.call.answered | On answer | answeredAt |
media_stream.call.completed | Ended after answer | reason, answeredAt, endedAt, durationSeconds |
media_stream.call.failed | Ended without answer | Same (answeredAt null, durationSeconds 0) |
{
"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
}
}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.
eventIdis a UUID. - Inbound events are sent up to three times: immediately, then after 2 and 5 seconds.
eventIdis"{callId}:{type}". Inbound calls have noringingevent. - 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,
callIdis the same as the call history ID. For outbound calls, the call history ID iscallHistoryId.
WebSocket messages
KAT 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.
| Header | Value |
|---|---|
X-Kat-Call-Id | Call ID (same as start.callId) |
X-Kat-Stream-Id | Stream ID (same as start.streamId, MZ + 32 characters) |
X-Webhook-Timestamp | Unix time (seconds) |
X-Webhook-Signature | v1= + HMAC-SHA256(webhook secret, "{timestamp}.{callId}.{streamId}") in hex |
Audio format
- G.711 8 kHz mono.
PCMU(μ-law, default) orPCMA(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.
| event | When |
|---|---|
connected | Once, right after connecting |
start | Once, when call audio is connected (after the call-start announcement, if any) |
media | Every 20 ms of the other party's audio |
dtmf | The other party pressed a keypad key (0-9 * #) |
mark | All audio sent before your mark has finished playing (immediately on clear) |
stop | The call ended. The socket is then closed (code 1000) |
{ "event": "connected", "protocol": "Call", "version": "1.0.0" }
{
"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"
}
}
{
"event": "media",
"sequenceNumber": "2",
"streamSid": "MZ5c0e2b1a9d8e4f7a6b5c4d3e2f1a0b9c",
"media": { "track": "inbound", "chunk": "1", "timestamp": "20", "payload": "f39/fn5+…" }
}
{ "event": "dtmf", "sequenceNumber": "40", "streamSid": "MZ5c…", "dtmf": { "digit": "1", "track": "inbound_track" } }
{ "event": "mark", "sequenceNumber": "41", "streamSid": "MZ5c…", "mark": { "name": "greeting-end" } }
{
"event": "stop",
"sequenceNumber": "99",
"streamSid": "MZ5c…",
"stop": { "accountId": "KAT789", "callId": "3f0c…", "accountSid": "KAT789", "callSid": "3f0c…" }
}accountIdisKAT+ the group ID.streamSid,callSid, andaccountSidrepeat the same values for Twilio Media Streams compatibility.mediaFormat.encodingisaudio/x-alawfor PCMA.customParametersis themetadatafrom the request or webhook response, or{}if none.media.chunkstarts at 1 and increases; a missing number means a lost chunk.media.timestampis the elapsed ms sincestart.- For outbound calls,
fromis your caller number andtois the callee. For inbound calls,fromis the caller andtois 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.
| event | Body | Behavior |
|---|---|---|
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 |
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
| Cause | Outbound reason | Inbound reason |
|---|---|---|
| Other party hung up | REMOTE_HANGUP | REMOTE_HANGUP |
| Your server closed the socket | STREAM_ENDED | STREAM_ENDED |
| Connecting to streamUrl failed | STREAM_CONNECT_FAILED (after answer, so call fees apply) | STREAM_CONNECT_FAILED (not answered) |
| Hang-up API | CUSTOMER_TERMINATED | — |
| timeLimit exceeded | MAX_DURATION | — (no duration limit for inbound) |
| KAT Cloud error | SYSTEM_FAILURE | SYSTEM_FAILURE |
Example server
// 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).
| Method | Path | Description |
|---|---|---|
| POST | /group/{groupId}/agent | Create agent (201, 20 per group) |
| GET | /group/{groupId}/agent | List 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}/revision | Revision history |
What differs by direction
| Inbound (INBOUND) | Outbound (OUTBOUND) | |
|---|---|---|
| Call start | The caller dials a bound number (number binding) | The agent places the call through an AI outbound call request |
greeting | First greeting, read exactly as written right after the call connects | Guidance 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 fields | Not used | outboundInputSchema defines the values each outbound call request receives |
| Number binding | Required | Not used. The caller number is chosen with callerChannelId in the outbound call request |
| Transfer to a person | Follows the group's call forwarding number setting | Not done |
Create and manage agents
/group/{groupId}/agentCreates 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).
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Agent name (100 characters or fewer) |
direction | string | Required | INBOUND for inbound calls / OUTBOUND for outbound calls. Cannot be changed after creation |
prompt | string | Required | Role, goals, tone, and prohibited actions (8,000 characters or fewer) |
status | string | Optional | ACTIVE (default) / DISABLED — not used for calls |
context | string | null | Optional | Background information such as company and products (8,000 characters or fewer) |
greeting | string | null | Optional | First greeting or opening-line guidance (600 characters or fewer). Meaning differs by direction (see greeting below) |
voice | string | null | Optional | HIGH_FEMALE · LOW_FEMALE · HIGH_MALE · LOW_MALE. If empty, the group voice is used |
language | string | null | Optional | KO · EN · JA · ZH · TH. If empty, the group default language is used |
liveModel | string | null | Optional | Voice 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) |
maxCallSeconds | number | null | Optional | Maximum call duration (seconds, 30–480). If empty, 480 |
aiInterruptionEnabled | boolean | null | Optional | Interruption. 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 |
outboundInputSchema | object | null | Optional | OUTBOUND 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.
{
"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
}
{
"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.
| Field | Type | Description |
|---|---|---|
id | number | Agent ID (agentId) |
groupId | number | Group ID |
version | number | Agent version. Increases by 1 whenever the agent body, manuals, or tools change |
createdAt | string | Creation time (ISO 8601) |
updatedAt | string | Last update time (ISO 8601) |
/group/{groupId}/agentReturns 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.
| Query | Type | Required | Description |
|---|---|---|---|
direction | string | Optional | Filter by INBOUND or OUTBOUND |
status | string | Optional | Filter by ACTIVE or DISABLED |
GET /group/1/agent?direction=INBOUND&status=ACTIVE/group/{groupId}/agent/{agentId}Returns one agent. If the agent does not exist or was deleted, you get 404 AG001.
/group/{groupId}/agent/{agentId}- Fields you don't send are left unchanged.
- Sending
nullforcontext·greeting·voice·language·liveModel·maxCallSeconds·aiInterruptionEnabled·outboundInputSchemaclears it, and the group value or default is used. name·prompt·statusdo not acceptnull(400 GL002).directioncannot be changed. If it is in the body, it is not ignored but rejected with400 GL002.- Changing
outboundInputSchemare-checks that theinputBindingsof this agent’s tools match the new schema. If any tool does not match, you get400 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.
{
"greeting": null,
"status": "DISABLED"
}/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, sendinputsas{}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.
| source | Shape | Value 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
valueofCONSTANTmust match that argument’s type. - The
fieldofOUTBOUND_INPUTmust be in the agent’soutboundInputSchema.propertiesand have the same type as the argument (integerandnumberalso count as different types). Tools of INBOUND agents cannot useOUTBOUND_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 returns400 AO005. It is safer to list bound fields inrequired.
{
"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"]
}
}
{
"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
}
{
"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.reason | Meaning |
|---|---|
INVALID_BINDINGS | inputBindings is not an object, or the tool inputSchema breaks the rules |
INVALID_BINDING_TARGET | Argument name not in inputSchema |
INVALID_BINDING | A CONSTANT entry has keys other than source · value |
UNREGISTERED_BINDING_INPUT | The OUTBOUND_INPUT field is not in the outbound input fields (including when the agent is INBOUND or has no outbound input fields) |
BINDING_TYPE_MISMATCH | The outbound input field and the tool argument have different types |
INVALID_BINDING_SOURCE | source is not CONSTANT · OUTBOUND_INPUT |
inputs.<argument>: … | The CONSTANT value does not match the argument type (for example, inputs.storeId: STRING_REQUIRED) |
{
"status": 400,
"code": "AO005",
"message": "발신 입력 또는 제한 설정이 올바르지 않습니다.",
"details": { "reason": "BINDING_TYPE_MISMATCH" }
}Revision history
/group/{groupId}/agent/{agentId}/revisionReturns 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.
[
{
"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
| Field | Type | Description |
|---|---|---|
version | number | Agent version |
snapshot | object | The full agent at that version (below) |
changedApiKeyId | number | null | The API key ID if the change was made with an API key. null means it was changed in the console |
createdAt | string | Recorded time (ISO 8601) |
snapshot
- The agent body fields (
directionand all create fields, includingoutboundInputSchema) plusmanualsandtools. manuals·toolsinclude every item that is not deleted (including disabled ones), sorted byidascending. A manual item has the shape of the manual response withoutaiAgentIdand the timestamps.- Tool items use some key names that differ from the tool response. The MCP allow list is
mcpAllowedTools, notallowedTools;mcpToolsexists only on MCP tools and has three fields:name·readOnly·usable. There is notoolName. - Tool auth values are not stored; only
hasAuthSecretis kept.authVersionis 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.
| Method | Path | Description |
|---|---|---|
| GET | /group/{groupId}/agent/{agentId}/manual | List manuals |
| POST | /group/{groupId}/agent/{agentId}/manual | Create manual (201) |
| PATCH | /group/{groupId}/agent/{agentId}/manual/{manualId} | Update manual |
| DELETE | /group/{groupId}/agent/{agentId}/manual/{manualId} | Delete manual |
Create and manage manuals
/group/{groupId}/agent/{agentId}/manual| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Manual name (100 characters or fewer) |
description | string | null | Optional | When 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 |
content | string | Required | Body (1,500 characters or fewer) |
isActive | boolean | Optional | Whether it is in use (default true). If off, it is not used for calls |
manualKind | string | Optional | GENERAL guidance (default) / NOTE record intake |
noteFields | object[] | null | Optional | For NOTE, the fields to record (up to 20). See record fields. For GENERAL, discarded without error and stored as null |
noteHandoffEnabled | boolean | Optional | For 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 |
{
"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
}
{
"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 byidascending. Disabled manuals are included. - Update (
PATCH) leaves fields you don’t send unchanged. Onlydescription·noteFieldscan be cleared by sendingnull; sendingnullfor other fields returns400 GL002. Changing NOTE to GENERAL also clearsnoteFields. If no value changed, the version does not increase. - Delete (
DELETE) returnsresult: null. - A missing manual returns
404 AG003; a missing agent returns404 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.
| Field | Type | Required | Description |
|---|---|---|---|
key | string | Required | Letters, 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 |
label | string | Required | Field name to confirm with the caller (80 characters or fewer) |
type | string | Optional | Field type (default TEXT, table below) |
required | boolean | Optional | Whether it is required (default true) |
description | string | Optional | Tips for collecting it (200 characters or fewer) |
options | string[] | Required for ENUM only | Choices (1–20, up to 40 characters each, no empty strings) |
| type | Value received |
|---|---|
TEXT | Free text |
NUMBER | Number |
BOOLEAN | Yes / No |
DATE | YYYY-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) |
TIME | HH:mm (24-hour). “9:30” is normalized to 09:30; other formats are not recorded |
PHONE | 9–11 digits starting with 0. If empty, the number the caller is calling from is used |
ENUM | One 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.
callerChannelId in the AI outbound call request.| Method | Path | Description |
|---|---|---|
| GET | /group/{groupId}/channel | List group phone numbers |
| GET | /group/{groupId}/agent/{agentId}/channel | List numbers bound to the agent |
| PUT | /group/{groupId}/agent/{agentId}/channel | Replace the list of bound numbers |
/group/{groupId}/channelThe 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.
[
{ "id": 100, "phoneNumber": "07012345678", "displayName": "Main number", "isPrimary": true },
{ "id": 101, "phoneNumber": "07012345679", "displayName": null, "isPrimary": false }
]| Field | Type | Description |
|---|---|---|
id | number | Number (channel) ID |
phoneNumber | string | Phone number |
displayName | string | null | Display name |
isPrimary | boolean | Whether it is the main number |
/group/{groupId}/agent/{agentId}/channelNumbers bound to the agent. The response has the same shape as above.
/group/{groupId}/agent/{agentId}/channelReplaces 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.
| Field | Type | Required | Description |
|---|---|---|---|
channelIdList | number[] | Required | Number IDs to bind. Up to 100; the same ID twice returns 400 GL002 |
{
"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.
| Method | Path | Description |
|---|---|---|
| GET | /group/{groupId}/agent/{agentId}/tool | List tools (id ascending, including disabled tools) |
| POST | /group/{groupId}/agent/{agentId}/tool | Create 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}/test | Test call (200) |
| POST | /group/{groupId}/agent/{agentId}/tool/{toolId}/refresh | Re-fetch the MCP tool list (200) |
Create and manage tools
/group/{groupId}/agent/{agentId}/tool| Field | Type | Required | Description |
|---|---|---|---|
kind | string | Optional | HTTP (default) / MCP. Cannot be changed after creation |
name | string | Required | Lowercase 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 |
description | string | Required | When to use it (1,000 characters or fewer). The agent reads this to choose a tool, so be specific |
url | string | Required | URL to call (500 characters or fewer). Must pass the URL checks below (AG011) |
httpMethod | string | Optional | HTTP: GET (default, arguments as query) / POST (arguments as JSON body) |
inputSchema | object | Optional | HTTP: JSON Schema of the arguments (argument schema rules below). If omitted, no arguments. If invalid, 400 AG013 |
inputBindings | object | null | Optional | HTTP: fills some arguments with fixed values or outbound input values. See outbound input fields. If invalid, 400 AO005 |
authType | string | Optional | NONE (default) / BEARER → Authorization: Bearer <authSecret> / HEADER → <authHeaderName>: <authSecret> |
authHeaderName | string | null | For HEADER | Auth header name (letters, digits, and hyphens, 100 characters or fewer). The disallowed names below are rejected |
authSecret | string | null | For BEARER · HEADER | Auth value (1,000 characters or fewer). Stored encrypted and never returned in responses |
timeoutMs | number | Optional | Time to wait for a response (ms, 1000–8000). Default 5000 |
write | boolean | Optional | HTTP: 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) |
allowedTools | string[] | null | Optional | MCP: names of server tools to expose to the agent (up to 50, 64 characters each). If empty (null), all usable tools |
isActive | boolean | Optional | If off, not used for calls (default true) |
{
"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
}
{
"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.
| Field | Type | Description |
|---|---|---|
id | number | Tool ID (toolId) |
aiAgentId | number | Agent ID |
toolName | string | Name the agent sees. ext_<name> for HTTP, mcp_<name>_<tool> for MCP (literally) |
hasAuthSecret | boolean | Whether an auth value is stored |
mcpTools | object[] | null | MCP: the server tool list last fetched (see MCP servers). null for HTTP |
createdAt · updatedAt | string | Creation and update times (ISO 8601) |
The fields below may be stored and returned differently from what you sent.
| Field | Response value |
|---|---|
httpMethod · inputSchema | null for MCP tools, regardless of what was sent |
write | Always false for MCP tools (set per server tool by readOnlyHint) |
allowedTools | null for HTTP tools, regardless of what was sent |
authHeaderName | null unless authType is HEADER |
hasAuthSecret | false 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 asformat·$ref·oneOfare not accepted. typeis one ofstring·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.
descriptionis up to 300 characters.enumis only forstring, with 1–50 values of up to 100 characters each.arrayrequiresitems, andrequiredmay list only names inproperties.
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).
| reason | Meaning |
|---|---|
| 주소 형식이 아닙니다. | 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.
| Case | errors[0].field | reason |
|---|---|---|
| MCP alias (name) is 17 characters or more | name | MCP 서버 별칭은 16자까지입니다. |
| HEADER with no header name or a disallowed name | authHeaderName | HEADER 인증에는 다른 헤더와 겹치지 않는 헤더 이름이 필요합니다. |
| BEARER · HEADER with no authSecret | authSecret | BEARER 인증에는 authSecret 이 필요합니다. |
| allowedTools contains a tool name not on the server or not usable on calls | allowedTools | 서버에 없거나 통화에 쓸 수 없는 도구입니다 (mcpTools 의 usable 을 보세요). |
| refresh on an HTTP tool | toolId | MCP 도구만 새로고칩니다. |
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)
/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·allowedToolscan be cleared by sendingnull.allowedTools: nullreverts to all usable tools.- Sending only
authSecretasnullwhile authType stays BEARER · HEADER returns400 GL002. To remove auth, changeauthTypetoNONE. kindcannot be sent (400 GL002). To switch between HTTP and MCP, create a new tool.writeapplies only to HTTP tools, andallowedToolsonly 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.
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: 9c2d1e7f0a4b8c3d6e5f1a2b3c4d5e6f7a8b9c0dRequest headers
| Header | When | Value |
|---|---|---|
Accept | Always | application/json |
User-Agent | Always | ZeroCall-AI-Agent |
X-Zerocall-Agent-Id | Always | Agent ID |
X-Zerocall-Call-Id | During a call | Call history ID (callHistoryId). Can be matched with call history and CALL_COMPLETED |
X-Zerocall-Caller | When the caller number is available | Caller phone number. Use it to check that the order belongs to the caller. Absent on calls with a hidden caller ID |
Idempotency-Key | Every call made during a call | 40 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 |
Authorization | authType BEARER | Bearer <authSecret> |
| <authHeaderName> | authType HEADER | authSecret |
Content-Type | POST | application/json |
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
| Result | What the agent says |
|---|---|
| 2xx | Responds 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 failure | Does 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
confirmedargument 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-Keyon 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.
{
"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"]
}
{
"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/listis fetched and stored (up to 5 pages). If it cannot be fetched, you get400 AG015with the connection failure reason inerrors[0].reason. It is not fetched again during calls, so call refreshwhen you change the server’s tools. - Only tools with
usable: truethat are inallowedTools(if set) are attached to calls. Thedescriptionof the registered MCP tool is appended in parentheses after each tool description. - Only tools with
readOnlyHint: trueare treated as lookup tools; the rest are called like write tools, after reading back and getting confirmation.
| Field | Type | Description |
|---|---|---|
name | string | Tool name on the server |
toolName | string | Name 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 |
description | string | Tool description (up to 1,000 characters) |
readOnly | boolean | true only when the server gives annotations.readOnlyHint: true |
usable | boolean | Whether it can be used on calls (see schema handling below) |
unusableReason | string | null | Why it cannot be used |
Argument schema handling
- Tools with
anyOf·oneOf·allOf·$ref·not·if·patternPropertiesareusable: false. - Other constraints such as
format·minLengthare 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
typeis missing, it is inferred from the shape (object ifpropertiesis present, array ifitemsis present, string ifenumis present).enumis 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 withoutinputSchemais 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-Idduring a call,X-Zerocall-Callerwhen the caller number is available, and the auth header. Unlike HTTP tools, theAccept·User-Agent·Idempotency-Keyheaders are not sent. - The deduplication key is sent in
params._meta["zerocall/idempotencyKey"]oftools/call. It is computed the same way as the HTTP toolIdempotency-Key. - For the result,
structuredContentis used if present; otherwise the text parts ofcontentare 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: trueis 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
/group/{groupId}/agent/{agentId}/tool/{toolId}/testActually 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.
| Field | Type | Required | Description |
|---|---|---|---|
args | object | Optional | Arguments the agent would send (default {}). Do not include arguments bound with inputBindings |
callerPhoneNumber | string | Optional | Test number to send as X-Zerocall-Caller (9–11 digits starting with 0) |
outboundInputs | object | Optional | Outbound 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.
CONSTANTbindings are filled with their fixed values andOUTBOUND_INPUTbindings with values fromoutboundInputs, then checked againstinputSchema. If they do not match, your server is not called and the reason is returned inerror. - 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-Keyare not sent, andX-Zerocall-Calleris sent only whencallerPhoneNumberis 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,statusis 200 andbodyPreviewcontains a JSON string withname·readOnly·usablefor each tool.
{
"args": { "orderNo": "A-1024" },
"callerPhoneNumber": "01012345678"
}
{
"ok": true,
"status": 200,
"latencyMs": 182,
"bodyPreview": "{\"orderNo\":\"A-1024\",\"status\":\"IN_TRANSIT\",\"eta\":\"2026-11-18\"}",
"truncated": false,
"error": null
}
{
"args": { "answer": "CONFIRM" },
"outboundInputs": { "customerName": "Minji Kim", "reservationId": "R-2041" }
}Response fields
| Field | Type | Description |
|---|---|---|
ok | boolean | Whether the server responded with 2xx |
status | number | null | Status code from your server. null if the request could not be sent |
latencyMs | number | Elapsed time (ms) |
bodyPreview | string | null | Start of the response (up to 2,000 characters). JSON is converted back to a string |
truncated | boolean | Whether the response exceeds 32KB and is also cut during calls |
error | string | null | Reason for argument validation failure, timeout, blocked URL, or connection failure (for example, 5초 안에 응답이 없습니다. [no response within 5 seconds], 연결하지 못했습니다 (ECONNREFUSED). [could not connect]) |
/group/{groupId}/agent/{agentId}/tool/{toolId}/refreshRe-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).
data.groupId to tell them apart in events that include it.Managing webhooks
| Method | Path | Description |
|---|---|---|
| GET | /webhook | List registered webhooks |
| POST | /webhook | Register a webhook (201) |
| PATCH | /webhook/{webhookId} | Change the URL |
| DELETE | /webhook/{webhookId} | Delete |
| POST | /webhook/{webhookId}/test | Send a test notification (201) |
| GET | /webhook/secret | Get the signing secret — see Signature verification |
| POST | /webhook/secret/rotate | Rotate the signing secret — see Signature verification |
List
/webhookReturns the webhooks registered on the account, in the order they were created.
[
{
"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
/webhook| Field | Type | Required | Description |
|---|---|---|---|
eventType | string | Yes | MESSAGE_RECEIVED · SEND_RESULT · CALL_RECEIVED · CALL_COMPLETED · INTAKE · AI_OUTBOUND · MEDIA_STREAM |
url | string | Yes | URL that receives notifications (see the rules below) |
{
"eventType": "AI_OUTBOUND",
"url": "https://example.com/webhook/outbound"
}
{
"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://andhttps://URLs are accepted. Usehttpsin production.- The domain must resolve to a public address.
localhostand 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.
| Status | Code | When |
|---|---|---|
| 400 | GL002 | eventType is not in the list, url is not a valid URL, or an unknown field was sent |
| 400 | PK008 | The URL can't be accepted. The reason is in message and errors[0].reason (e.g. 내부망·사설 주소로는 보낼 수 없습니다. — "cannot send to an internal or private address") |
| 409 | PK006 | This account already has a webhook for the same eventType — change its URL with PATCH |
{
"status": 400,
"code": "PK008",
"message": "내부망·사설 주소로는 보낼 수 없습니다.",
"errors": [{ "field": "url", "reason": "내부망·사설 주소로는 보낼 수 없습니다." }]
}Change URL · Delete
/webhook/{webhookId}| Field | Type | Required | Description |
|---|---|---|---|
url | string | Yes | New 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.
/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
/webhook/{webhookId}/testSends 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·INTAKEsenddatawith sample values (groupIdis 0).CALL_RECEIVED·CALL_COMPLETED·AI_OUTBOUND·MEDIA_STREAMsend an empty object ({}) asdata.
{
"eventId": "3e1f9a7c-2d4b-4c6e-8f0a-1b2c3d4e5f6a",
"eventType": "AI_OUTBOUND",
"timestamp": "2026-11-16T01:00:00.000Z",
"data": {},
"isTest": true
}
{
"success": true,
"statusCode": 200,
"responseTime": 150
}
{
"success": false,
"statusCode": 500,
"responseTime": 87,
"error": "Request failed with status code 500"
}
{
"success": false,
"responseTime": 0,
"error": "내부망·사설 주소로는 보낼 수 없습니다."
}| Field | Type | Description |
|---|---|---|
success | boolean | true if your server answered with 2xx within 10 seconds |
statusCode | number | HTTP status your server answered with. Absent if no response was received |
responseTime | number | Elapsed time (ms) |
error | string | Failure 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.
{
"eventId": "0b6f2c1e-3a4d-4b5c-9d8e-7f6a5b4c3d2e",
"eventType": "CALL_COMPLETED",
"timestamp": "2026-11-16T06:00:00.000Z",
"data": { }
}| Field | Type | Description |
|---|---|---|
eventId | string | Unique ID of one notification. Stays the same on redelivery |
eventType | string | The registered event type |
timestamp | string | When this attempt was sent (ISO 8601). New value on every redelivery |
data | object | Event-specific content (see the event list) |
isTest | boolean | Present 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
| Notification | Sent to | Attempts | Redelivery timing | eventId |
|---|---|---|---|---|
| MESSAGE_RECEIVED · SEND_RESULT · CALL_RECEIVED · CALL_COMPLETED · INTAKE | Webhook registered for that eventType | Up to 3 | About 5 seconds after a failure, then about 15 seconds after another failure | UUID |
| AI_OUTBOUND | AI_OUTBOUND webhook | Up to 3 | About 5 seconds after a failure, then about 10 seconds after another failure | UUID |
| MEDIA_STREAM — stream outbound call status | statusCallbackUrl in the outbound request → MEDIA_STREAM webhook | Up to 3 | About 5 seconds after a failure, then about 10 seconds after another failure | UUID |
| MEDIA_STREAM — stream inbound call status | statusCallbackUrl in the incoming-call response → statusCallbackUrl in the number settings → MEDIA_STREAM webhook | Up to 3 | Sent 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 settings | 1 (not redelivered) | — (must answer within 5 seconds) | UUID |
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.
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",...}| Header | Description |
|---|---|
X-Webhook-Timestamp | Signing time (Unix seconds) |
X-Webhook-Signature | v1=<hex>. HMAC-SHA256(secret, "<X-Webhook-Timestamp>.<raw body>") as lowercase hex |
Verification steps
- 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.
- Reject the request if
X-Webhook-Timestampdiffers from the current time by more than 5 minutes (a recommended value to prevent replay attacks). - Compute HMAC-SHA256 of
"<timestamp>.<raw body>"with the secret and prefix it withv1=. Use the secret string as is as the key, includingwhsec_. - Compare it with
X-Webhook-Signatureusing a constant-time comparison (Nodecrypto.timingSafeEqual, Pythonhmac.compare_digest), and reject with 401 if they differ. - If it passes, use
eventIdto 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.
/webhook/secretReturns the secret. If none exists yet, one is created and returned.
{
"secret": "whsec_3f1c9a7e5b2d8c4f6a0e1b3d5c7a9f2e4b6d8a0c1e3f5a7b9d2c4e6f8a0b1c3d"
}/webhook/secret/rotateIssues 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.
Node.js (Express)
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)
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
| eventType | data.type | When | Details |
|---|---|---|---|
MESSAGE_RECEIVED | — | A customer sent a text message to a KAT number | MESSAGE_RECEIVED below |
SEND_RESULT | — | The final delivery result arrived for a message the group sent | SEND_RESULT below |
CALL_RECEIVED | — | An AI agent transfers a call to the call forwarding number | CALL_RECEIVED below |
CALL_COMPLETED | — | A call ended and transcript and summary processing finished | CALL_COMPLETED below |
INTAKE | — | An AI agent saves, changes, or cancels a record-type intake (immediately, during the call) | INTAKE |
AI_OUTBOUND | ai_outbound.call.ended | Once, when an AI outbound call ends (including unanswered calls) | AI outbound webhook |
AI_OUTBOUND | ai_outbound.analysis.completed | Once, when the transcript and summary of a recorded AI outbound call are finished | AI outbound webhook |
MEDIA_STREAM | media_stream.call.incoming | A call arrived at a stream inbound number. Sent only to webhookUrl in the number settings; your response decides whether to answer | Stream inbound calls |
MEDIA_STREAM | media_stream.call.ringing | A stream outbound call is ringing (outbound only, and only when a ringing signal arrives) | Status webhooks |
MEDIA_STREAM | media_stream.call.answered | A stream call was answered | Status webhooks |
MEDIA_STREAM | media_stream.call.completed | An answered stream call ended | Status webhooks |
MEDIA_STREAM | media_stream.call.failed | The call ended without being answered | Status 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.
{
"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"
}
}| Field | Type | Description |
|---|---|---|
data.chatId | string | Message ID (32 characters) |
data.chatRoomId | string | Chat room ID (30 characters) |
data.groupId | number | Group ID |
data.channelId | number | ID of the receiving number (channel) |
data.phoneNumber | string | KAT number that received the message |
data.senderPhoneNumber | string | Customer number that sent it |
data.content | string | Message content |
data.subject | string | Subject. The field is omitted if there is none |
data.imageList | string[] | MMS image URLs. Empty array if none |
data.receivedAt | string | Received at (ISO 8601) |
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.
{
"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"
}
}| Field | Type | Description |
|---|---|---|
data.chatId | string | Message ID (32 characters) |
data.chatRoomId | string | Chat room ID (30 characters) |
data.groupId | number | Group ID |
data.channelId | number | ID of the sending number (channel) |
data.sendPhoneNumber | string | Sender number |
data.recvPhoneNumber | string | Recipient number |
data.content | string | Message content |
data.chatType | string | SMS · LMS · MMS · RCS · KAKAO |
data.sendStatus | string | SUCCESS (KAT Cloud handed the request to the carrier) · FAILED (failed at the request stage) |
data.resultStatus | string | Final result code from the carrier |
data.resultMessage | string | Meaning of the result code. "Unknown" if the code is not in the table |
data.sentAt | string | When 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.
{
"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"
}
}| Field | Type | Description |
|---|---|---|
data.callHistoryId | string | Call history ID |
data.groupId | number | Group ID |
data.groupName | string | Group name |
data.channelId | number | ID of the receiving number (channel) |
data.fromNumber | string | Caller number (customer) |
data.fromName | string | Caller name (when in contacts) |
data.toNumber | string | KAT number that received the call |
data.handOffReason | string | Why the AI agent transferred the call. Omitted if it transferred without a reason |
data.receivedAt | string | Transferred 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.
{
"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"
}
]
}
}| Field | Type | Description |
|---|---|---|
data.callHistoryId | string | Call history ID |
data.groupId | number | Group ID |
data.channelId | number | ID of the group's number (channel) |
data.fromNumber | string | Calling number |
data.toNumber | string | Called number |
data.isInbound | boolean | true for inbound calls, false for outbound calls (AI outbound calls, etc.) |
data.status | string | ANSWERED · MISSED · REJECTED · UNKNOWN |
data.tag | string | AI (AI only) · DIRECT (person only) · AI_TO_DIRECT (AI transferred to a person) · UNKNOWN |
data.duration | number | Call duration (seconds) |
data.summary | string | Call summary. Present only for recorded calls |
data.sttAI | object[] | Transcript of the AI segment {role, text, timestamp (seconds, decimal)}. Present only for recorded calls |
data.sttDirect | object[] | Transcript of the person segment. Same shape as sttAI. Present only for recorded calls |
data.recordingUrl | string | Recording 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.recordings | object | Recordings 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.startedAt | string | Call start time (ISO 8601) |
data.completedAt | string | When call processing finished and the notification was created (ISO 8601). May differ from when the call hung up |
data.agentId | number | ID of the custom AI agent that handled the call. Present only for custom agent calls |
data.agentVersion | number | Agent version used for the call (can be found in the revision history) |
data.agentDirection | string | Agent direction INBOUND · OUTBOUND |
data.intakes | object[] | 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 withoutrecordingUrl·recordings. To get them later, query call history details. intakesis 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".
{
"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"
}
}| Field | Type | Description |
|---|---|---|
data.intakeId | number | Intake ID. If this intake is changed or canceled in the same call, it arrives again with the same ID |
data.callHistoryId | string | Call history ID |
data.groupId | number | Group ID |
data.manualId | number | null | ID of the manual used for the intake (null if none) |
data.manualTitle | string | Manual name |
data.requestType | string | NEW 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.customerPhoneNumber | string | Customer phone number |
data.fields | object | Field key → value. Read it by the keys in the manual's noteFields. Fields not collected are null |
data.fieldLabels | object | Field key → field name (label) |
data.content | string | Intake content (human-readable text; dates include the weekday) |
data.summary | string | One-line summary |
data.updatedAt | string | When the intake was made or last changed (ISO 8601) |
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
| Item | Value |
|---|---|
| URL | https://studio-gateway.zerocall.kr/mcp |
| Transport | Streamable HTTP. No sessions; the response is a single JSON message (not SSE) |
| Authentication | x-api-key header (same key as REST). OAuth and the Authorization header are not accepted |
| Methods | POST only (GET and DELETE return 405) |
| Server name | kat-ai-outbound 1.1.0, tools only |
| Rate limit | All of /mcp counts as one limit: 1,200 requests per 60 seconds per key |
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
claude mcp add --transport http kat https://studio-gateway.zerocall.kr/mcp \
--header "x-api-key: $KAT_API_KEY"Cursor (~/.cursor/mcp.json)
{
"mcpServers": {
"kat": {
"url": "https://studio-gateway.zerocall.kr/mcp",
"headers": { "x-api-key": "zpa.123.your-key-here" }
}
}
}VS Code (.vscode/mcp.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)
{
"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.
| Tool | What it does | Equivalent REST API | Pricing |
|---|---|---|---|
list_numbers | Group numbers and number IDs (main number first) | GET /group/{groupId}/channel | — |
send_message | Send a message (SMS, LMS, MMS) | POST /message/send | Paid |
get_message_result | Message delivery result | GET /message/send-result/{chatId} | — |
list_calls | List call history | GET /call-history | — |
get_call | One call history record (transcript, summary, recording URL) | GET /call-history/{callHistoryId} | — |
list_outbound_agents | Outbound AI agents and their input fields | GET /group/{groupId}/agent?direction=OUTBOUND | — |
create_ai_outbound_call | Request an AI outbound call | POST /group/{groupId}/ai-outbound/calls | Paid |
get_ai_outbound_call | AI outbound call status and result | GET …/ai-outbound/calls/{requestId} | — |
list_ai_outbound_calls | List AI outbound calls (newest first) | GET …/ai-outbound/calls | — |
terminate_ai_outbound_call | Cancel or hang up an AI outbound call | POST …/ai-outbound/calls/{requestId}/termination | — |
issue_number | Add one more 070 number to the group | GET /group/{groupId}/numbers/quote · POST /group/{groupId}/numbers | Paid |
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
idempotencyKeyplusconfirmMonthlyFee: trueto add the number. The result is the same as REST.
| Field | Type | Required | Description |
|---|---|---|---|
idempotencyKey | string | Yes | Key identifying one add-number request, 1–128 characters. Shares the same key space as the REST Idempotency-Key |
confirmMonthlyFee | boolean | No | true once the user has confirmed the added monthly fee |
groupId | number | No | Omit if the key has only one group |
send_message
| Field | Type | Required | Description |
|---|---|---|---|
fromPhoneNumber | string | Yes | Sender number. A number in this group (list_numbers) |
toPhoneNumber | string | Yes | Recipient number |
content | string | Yes | Body, 1–2,000 characters. Long messages are sent as LMS |
subject | string | No | LMS/MMS subject, 64 characters or fewer |
imageList | string[] | No | Up to 3 MMS image keys (from POST /message/media/upload) |
idempotencyKey | string | Yes | 1–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
| Field | Type | Required | Description |
|---|---|---|---|
channelId | number | No | Filter by number ID |
phoneNumber | string | No | Part of the other party's or your number |
keyword | string | No | Search by summary content |
updatedAfter | string | No | ISO 8601. Only records changed after this time, oldest first (don't use with offset) |
offset · limit | number | No | Defaults 0 · 20 (limit 1–100) |
includeTracks | boolean | No | Include per-speaker recording URLs |
callHistoryId | string | Yes (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).
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"
}
}
}'{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"{\"chatId\":\"7f3e…\"}"}]}}
// 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.
| Method | Path | Description |
|---|---|---|
| GET | /payment/credit/summary | Credit balance and auto top-up settings (per account) |
| GET | /payment/credit/history | Credit usage and top-up history (per account) |
| GET | /payment/group/{groupId}/usage | The group's included usage and usage for the current period |
403 KC008 from these APIs; in that case, check the Billing screen in the console.Credit summary
/payment/credit/summaryReturns the current credit balance and auto top-up settings.
{
"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
}| Field | Type | Description |
|---|---|---|
creditBalance | number | Credit balance (KRW). Can be negative if an auto top-up failed and the account is unpaid |
billingStatus | string | ACTIVE · INACTIVE |
autoRechargeThreshold | number | Auto top-up runs when the balance falls below this value (KRW) |
autoRechargeAmount | number | Auto top-up amount (KRW) |
costMap | object | Unit price table with uppercase keys (CALL · AI_CALL · SMS · LMS · MMS · RCS · KAO · MOK). Not used to calculate KAT Cloud charges |
billingAnchorAt | string | null | Billing 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
/payment/credit/historyReturns credit deductions and top-ups, grouped by period. All dates are in Korea time. The query range is up to 1 year.
Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
startDate | string | No | Start date (Korea time YYYY-MM-DD, from 00:00 that day). Default: 1 year before endDate |
endDate | string | No | End date (Korea time YYYY-MM-DD, through the end of that day). Default: today |
type | string | No | Filter by one history type (table below). UNKNOWN matches rows with an empty type |
groupBy | string | No | Grouping unit: day · week · month. Default day. A week starts on Sunday |
fillEmptyBuckets | boolean | No | If true, periods with no history are filled with 0. Default false |
includeDetails | boolean | No | If true, details contains row-level history. Default false |
limit | number | No | Number of details, 1–500. Default 100 |
offset | number | No | Number 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.).
GET /payment/credit/history?startDate=2026-11-01&endDate=2026-11-30&includeDetails=true
{
"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
| Field | Type | Description |
|---|---|---|
effectiveStartDate | string | Start time actually applied (Korea time, inclusive) |
effectiveEndDate | string | End time actually applied (Korea time, exclusive — 00:00 on the day after endDate) |
totalCount | number | Number of history rows in the range |
totalAmount | number | Total amount in the range. Deductions are negative, top-ups are positive |
summary | object[] | Totals per groupBy period. Most recent period first |
summary[].periodStart · periodEnd | string | Period start (inclusive) and end (exclusive), Korea time |
summary[].count · totalAmount | number | Number of rows and total amount in the period |
summary[].startBalance · endBalance | number | Balance before the period's first row and after its last row |
summary[].amountByType | object | Total amount per type |
summary[].amountByUsageCategory | object | Total amount per usageCategory |
details | object[] | Row-level history, most recent first (only when includeDetails=true) |
details[].type · sourceType | string | History type (both have the same value) |
details[].amount | number | Amount. Negative for deductions, positive for top-ups |
details[].absAmount · direction | number · string | Absolute amount; DEBIT (deducted) · CREDIT (added) |
details[].balanceBefore · balanceAfter | number | Balance before and after this row |
details[].description | string | null | Reason, in Korean (for example, KAT monthly fee, or KAT usage fee with the billing period) |
details[].createdAt | string | Time (ISO 8601 UTC) |
hasMoreDetails | boolean | true 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.
| What | type | description example |
|---|---|---|
| Monthly fee (at period start) | PLAN_DEDUCT | KAT 월 요금 (개인) 26.11.16~26.12.16 (KAT monthly fee (Personal)) |
| Number and line monthly fee | PLAN_DEDUCT | KAT 번호·회선 월 요금 (…) 26.11.16~26.12.16 (KAT number and line monthly fee) |
| Plan upgrade difference | PLAN_DEDUCT | KAT 플랜 올리기 차액 (개인 → 비즈니스) … (KAT plan upgrade difference (Personal → Business)) |
| Usage fees beyond included usage (multiple rows as usage accrues during the period) | USAGE_DEDUCT | KAT 사용료 26.11.16~26.12.16 (KAT usage fee) |
| Refund when an AI outbound call included in usage fees becomes waived (positive) | MANUAL_ADJUST | KAT AI 발신 면제 환급 (요청 {requestId}) (KAT AI outbound waiver refund (request {requestId})) |
| Top-up (auto or manual) | AUTO_RECHARGE | 크레딧 충전 (credit top-up) |
type values
| Value | Meaning |
|---|---|
USAGE_DEDUCT | Usage fee deduction |
PLAN_DEDUCT | Plan or monthly fee deduction |
AUTO_RECHARGE | Credit top-up |
MANUAL_ADJUST | Adjustment (refunded amounts, etc.) |
AI_CALL_REFUND | AI call refund |
CAMPAIGN_USAGE | Campaign (bulk SMS) usage |
STORAGE_FEE_DEDUCT | Recording storage fee |
STT_USAGE_DEDUCT | Call analysis fee |
UNKNOWN | type 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
/payment/group/{groupId}/usageReturns 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.
| Field | Type | Required | Description |
|---|---|---|---|
groupId | number | Yes | Group ID (path). 403 PK004 if it is not the group bound to the key |
{
"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.
| Field | Type | Description |
|---|---|---|
katcloud.status | string | TRIAL (in trial) · TRIAL_ENDED (trial ended) · ACTIVE (on a paid plan) · UNPAID (unpaid) · SUSPENDED (suspended) · CANCELED (canceled) |
katcloud.plan | string | PERSONAL · BUSINESS. The trial uses the Personal (PERSONAL) plan's included usage |
katcloud.included | object | Included usage. outboundMinutes · inboundMinutes in minutes, sms in messages (no included usage for LMS or MMS) |
katcloud.usage.outboundMinutes | number | Outbound minutes (rounded up to 1 minute per call) |
katcloud.usage.inboundMinutes | number | Inbound minutes (rounded up to 1 minute per call) |
katcloud.usage.sms · lms · mms | number | Messages sent (excluding failed and canceled) |
katcloud.usage.aiAgentMinutesByModel | object | Minutes handled by AI agents, per voice model name (rounded up to 1 minute per call) |
katcloud.usage.transcriptionMinutes | number | Transcript minutes (call duration of recorded calls) |
katcloud.usage.summaryMinutes | number | Summary minutes (call duration of recorded calls) |
katcloud.usageCharged | number | Usage 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
| Call | Outbound/inbound minutes | AI agent minutes | Transcript and summary minutes |
|---|---|---|---|
| Call answered by an AI agent | inboundMinutes | Counted per model | Counted if recorded |
| Call transferred to a forwarding number | inboundMinutes + the transferred portion also in outboundMinutes | AI-handled portion only | Counted if recorded |
| AI outbound call | outboundMinutes | Counted per model | Counted if recorded |
| Stream outbound | outboundMinutes | 0 | 0 (no transcript or summary is produced) |
| Stream inbound | inboundMinutes | 0 | Counted 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 (
settlementStatusWAIVED) are not added. To see the settlement status of a single call, checksettlementStatusin 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.
| Field | Type | Description |
|---|---|---|
groupId | number | Group ID |
plan | string | Same as katcloud.plan |
startDate · endDate | string | Period start and end (ISO 8601 UTC). Trial start and end during the trial |
initialCallMinute · initialCallSecond | number | Outbound included usage (minutes · seconds) |
useCallMinute · useCallSecond · billedCallSecond | number | Outbound usage (minutes, rounded up to 1 minute per call · the same in seconds) |
remainingCallMinute · remainingCallSecond | number | Remaining outbound included usage (minutes · seconds, never below 0) |
initialMessageCount | number | SMS included usage (messages) |
useSmsCount · useLmsCount · useMmsCount | number | Messages sent |
useTotalMessageCount | number | Total messages sent |
remainingMessageCount | number | Remaining SMS included usage (LMS and MMS have no included usage) |
initialAiCallCount · useAiCallCount · remainingAiCallCount | number | Always 0 for KAT groups |
Errors
| Status | Code | When |
|---|---|---|
| 403 | PK004 | Not the group bound to the key, or groupId is not a number |
| 404 | GR001 | No trial or billing period record for the group |
| 403 | KC008 | Group 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.
| Field | Type | Description |
|---|---|---|
status | number | Same value as the HTTP status code |
code | string | Error code. Use it to branch your handling |
message | string | Description. 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 |
details | object | Additional information. Present only when set (for AO005 from AI outbound calls and media streams, the reason is in details.reason) |
{
"status": 400,
"code": "GL002",
"message": "필수 값입니다.",
"errors": [{ "field": "toPhoneNumber", "reason": "필수 값입니다." }]
}
{
"status": 400,
"code": "AO005",
"message": "발신 입력 또는 제한 설정이 올바르지 않습니다.",
"details": { "reason": "inputs.customerName: REQUIRED" }
}
{
"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.messagemay 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
| Status | Meaning | Typical codes |
|---|---|---|
| 400 | The request is invalid | GL002, G400, API-specific codes |
| 401 | The key is missing or invalid | AU011, AU012 |
| 402 | Insufficient credit | CB001, GR016 |
| 403 | Rejected due to permissions or group state | PK004, KC008, GR076, AO002, GL011 |
| 404 | Resource or path not found | AG001, AO015, CR001, G404 |
| 409 | Already exists or conflicts with an earlier request | AG008, AG014, AO006, PK006, KC102 |
| 413 | Request or file too large | GL003, G413 |
| 415 | Unsupported file | GL007 |
| 429 | Too many calls | G429 (rate limit), AO013·AO014 (outbound call limits), KC103 (adding numbers limit) |
| 500 | Server error | GL001, GL008 |
| 502·503 | Cannot be processed right now | KC035, CH002, AO009, AO020 |
Common error codes
| Code | HTTP | message | When · What to do |
|---|---|---|---|
GL001 | 500 | 내부 서버 오류입니다. | Unexpected server error. Follow the retry table below |
GL002 | 400 | 잘못된 요청입니다. | 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 |
GL003 | 413 | 요청 크기가 너무 큽니다. | The body exceeds 100MB |
GL011 | 403 | 국외 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 |
G400 | 400 | (message set by the API) | Rejected with a message the API set itself. May be in English |
G404 | 404 | 요청한 경로를 찾을 수 없습니다. | Unknown path or method |
G413 | 413 | File too large | The uploaded file exceeds 10MB |
G429 | 429 | 요청이 너무 많습니다. 잠시 후 다시 시도해 주세요. | 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.
| reason | Meaning |
|---|---|
| 허용되지 않은 필드입니다. | 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
| Error | Safe to retry | How |
|---|---|---|
G429 | Yes | After waiting Retry-After seconds. The request was blocked before processing, so you can resend any API request as is |
| GL001 · 5xx · connection failure · timeout | Only reads (GET) and outbound calls sent with an Idempotency-Key | Whether 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 |
KC035 | Yes | Failed to generate the announcement audio. Try again shortly |
AO013 | Later | After an in-progress outbound call ends, resend with the same Idempotency-Key |
AO014 | Later | Retry the next day (Korean date) |
AO012 | Later | Retry within the allowed outbound call hours |
| AO009 · AO020 · CH002 | After a short wait | The feature is unavailable right now. If it persists, contact KAT Cloud |
| Other 4xx | No | The 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.
| Code | HTTP | message | When · What to do |
|---|---|---|---|
AU011 | 401 | API 키가 필요합니다. | The x-api-key header is missing. The Authorization header is not read |
AU012 | 401 | 유효하지 않거나 만료된 API 키입니다. | The key is malformed, does not exist, or has expired or been revoked. Check the console API keys page |
GR076 | 403 | 운영 정책에 따라 이용이 정지된 계정이에요. 고객센터로 문의해 주세요. | The group was suspended by an operator. Contact KAT Cloud |
PK004 | 403 | 해당 그룹에 대한 접근 권한이 없습니다. | A groupId not bound to the key, a non-numeric path groupId, or another group's resource |
KC008 | 403 | 체험이 끝났거나 이용이 멈춘 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 |
KC006 | 403 | KAT Cloud 번호는 콘솔에서 받습니다. Studio API로 그룹을 만들거나 지울 수 없습니다. | POST /group, DELETE /group/{groupId}. To get more numbers, use the adding numbers API |
KC101 | 403 | 유료 플랜을 쓰는 중일 때만 번호를 추가할 수 있습니다. 체험·미납·정지 중이면 KAT Cloud 콘솔에서 결제를 먼저 확인해 주세요. | Adding numbers. The group is on a trial, unpaid, or suspended |
KC102 | 409 | 직접 추가로는 그룹 번호를 30개까지 둘 수 있습니다. 더 필요하면 KAT Cloud 담당자에게 요청해 주세요. | Adding numbers. The group already has 30 numbers |
KC103 | 429 | 그룹 하나에 1시간에 번호 3개까지 추가할 수 있습니다. 잠시 뒤 다시 시도해 주세요. | Adding numbers. This group has already added 3 numbers within the past hour (console, API and MCP combined) |
KC007 | 403 | KAT Cloud 그룹은 멤버를 두지 않습니다. 직원 연결은 콘솔의 넘길 번호로 설정해 주세요. | Member APIs. Set the number for transferring to staff with the call forwarding number API or in the console |
KC012 | 403 | 체험에 포함된 문자를 모두 사용했습니다. | POST /message/send during a trial. Check included usage with Included usage and usage |
KC013 | 400 | 휴대폰·지역번호·070 번호만 넘길 번호로 쓸 수 있습니다. | PATCH /group/{groupId}/call-forward |
GR007 | 400 | 착신전환 활성화 시 전화번호가 필요해요! | Enabling the call forwarding number without a number to use |
KC031 | 400 | 올릴 수 없는 음성 파일입니다. WAV 나 MP3 파일을 올려 주세요. | Upload announcement audio. message may be replaced with a specific reason |
KC032 | 400 | 안내 음성 파일을 먼저 올려 주세요. | Audio file mode is selected but no file has been uploaded |
KC033 | 400 | 안내 문구를 입력해 주세요. | Text mode is selected but the text is empty |
KC034 | 400 | 안내 멘트는 20초 이내여야 합니다. | The announcement is longer than 20 seconds |
KC035 | 502 | 안내 음성을 만들지 못했습니다. 잠시 후 다시 시도해 주세요. | Failed to generate audio from the text. Try again shortly |
KC036 | 404 | 아직 만들어진 안내 음성이 없습니다. | Download announcement audio |
KC037 | 400 | 안내 멘트 설정은 inbound·outbound 로 나눠 보내거나, 예전 방식(enabled·direction·messageType)으로 보내 주세요. | Mixed the two formats of call-start announcement settings |
PV001 | 400 | 전화번호 형식이 올바르지 않아요 (숫자 7~15자리, 하이픈·+82 허용) | Delete by other party's number |
PV002 | 400 | 그룹에 연결된 번호는 상대 번호로 지울 수 없어요 | Passed your own group number as the other party's number |
PV004 | 404 | 통화 기록을 찾을 수 없어요 | Delete a single call history record |
PV005 | 400 | 마스킹 시점은 12~36개월 사이 정수이거나 null(기본 3년) 이어야 해요 | Call history retention settings |
PK005 | 404 | 존재하지 않는 Webhook 설정입니다. | Update, delete, or test a webhook configuration |
PK006 | 409 | 해당 이벤트 타입의 Webhook이 이미 존재합니다. | Each event type can have only one webhook |
PK008 | 400 | 이 주소로는 웹훅을 받을 수 없습니다. | 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.
| Code | HTTP | message | When · What to do |
|---|---|---|---|
AO001 | 404 | 접근할 수 있는 캣클라우드 그룹이 없습니다. | Not a KAT Cloud group, or a deleted group. Usually does not occur with keys created in the console |
AO002 | 403 | AI 발신 이용 승인이 없거나 현재 발신을 사용할 수 없습니다. | 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 |
AO005 | 400 | 발신 입력 또는 제한 설정이 올바르지 않습니다. | Invalid destination number format, Idempotency-Key format, inputs, stream URL, metadata, call duration, or cursor. The reason is in details.reason |
AO006 | 409 | 같은 멱등 키에 다른 발신 요청을 사용할 수 없습니다. | Sent a different body with the same Idempotency-Key. Use a new key for a new outbound call |
AO007 | 404 | 사용할 수 있는 발신 상담원이 없습니다. | The agentId does not exist, is not for outbound calls (OUTBOUND), or is not on (ACTIVE) |
AO008 | 409 | 도구 인증 버전이 변경되거나 폐기되었습니다. | An HTTP tool of the AI agent that requires authentication has no secret. Set the authSecret of the tool again |
AO009 | 503 | AI 발신 실행은 아직 공개되지 않았습니다. | AI outbound calls are not being accepted right now. If it persists, contact KAT Cloud |
AO010 | 400 | 그룹에서 사용할 수 있는 정상 개통 발신번호가 아닙니다. | callerChannelId is not an active group number. Find IDs with GET /group/{groupId}/channel |
AO011 | 403 | 차단 또는 수신거부한 번호로 발신할 수 없습니다. | The number is blocked by the group or has opted out of calls from this caller number |
AO012 | 403 | AI 발신 허용 시간이 아닙니다. | Outside the allowed outbound call hours (default 08:00–21:00 Korea time) |
AO013 | 429 | 동시에 발신할 수 있는 통화 수를 초과했습니다. | The concurrent outbound call limit is full. AI outbound calls and stream outbound calls count together |
AO014 | 429 | 오늘 발신할 수 있는 통화 수를 초과했습니다. | The daily outbound call limit (by Korean date) is used up. AI outbound calls and stream outbound calls count together |
AO015 | 404 | 접근할 수 있는 발신 요청이 없습니다. | Unknown request ID. Also returned when looking up an AI outbound call ID through a stream path |
AO016 | 403 | 사용할 수 있는 체험 잔여량 또는 유료 구독이 없습니다. | Less than 1 minute of trial outbound included usage remains and there is no paid plan. Check the console Billing page |
AO020 | 503 | 미디어 스트림은 아직 공개되지 않았습니다. | Media streams are not being accepted right now. If it persists, contact KAT Cloud |
AO021 | 404 | 그룹에서 쓸 수 있는 KAT 번호가 아닙니다. | The from number of a stream outbound call, or the number in inbound call settings, is not a KAT number in your group |
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.
{
"status": 400,
"code": "AG011",
"message": "https 주소만 쓸 수 있습니다.",
"errors": [{ "field": "url", "reason": "https 주소만 쓸 수 있습니다." }]
}| Code | HTTP | message | When · What to do |
|---|---|---|---|
AG001 | 404 | 존재하지 않는 AI 상담원입니다. | The AI agent does not exist, was deleted, or belongs to another group |
AG002 | 403 | 이 그룹은 커스텀 AI 상담원을 쓸 수 없습니다. 제로콜에 사용 신청을 해 주세요. | The group's AI agent feature is off. KAT groups are created with it on; if you see this, contact KAT Cloud |
AG003 | 404 | 존재하지 않는 상담원 매뉴얼입니다. | Update or delete a manual |
AG004 | 400 | 상담원 하나에 매뉴얼은 30개까지 등록할 수 있습니다. | Create a manual |
AG006 | 400 | 이 그룹의 전화번호만 연결할 수 있습니다. | Passed another group's number ID when connecting a number |
AG007 | 400 | 이 그룹은 운영시간·운영시간 외 모두 사람만 전화를 받도록 되어 있어 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 |
AG008 | 409 | 이미 다른 받는 전화용 상담원이 연결된 번호가 있습니다. 그 상담원의 연결을 먼저 끊어 주세요. | A number can be connected to only one inbound AI agent |
AG009 | 400 | 그룹 하나에 AI 상담원은 20개까지 등록할 수 있습니다. 쓰지 않는 상담원을 지운 뒤 등록해 주세요. | Create an AI agent |
AG010 | 404 | 존재하지 않는 상담원 도구입니다. | Update, delete, refresh, or test-call a tool |
AG011 | 400 | 이 주소로는 도구를 등록할 수 없습니다. | Not https, the URL contains user info, or it is an internal or private address. The reason is in errors[0].reason |
AG012 | 400 | 상담원 하나에 도구는 10개까지 등록할 수 있습니다. | HTTP and MCP tools are counted together |
AG013 | 400 | 도구 인자(inputSchema)를 받을 수 없는 모양입니다. | inputSchema does not follow the rules. The reason is in errors[0].reason |
AG014 | 409 | 이 상담원에 같은 이름의 도구가 있습니다. | Tool names must be unique within an AI agent |
AG015 | 400 | MCP 서버에서 도구 목록을 받지 못했습니다. | 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.
| Code | HTTP | message | When · What to do |
|---|---|---|---|
CH001 | 404 | 존재하지 않는 채널이에요! | Send message / create chat room: the sender number is not a number in your group |
CH001 | 404 | 존재하지 않는 문자에요! | Get send result: the chatId does not exist or is not a message sent through the API |
CH002 | 503 | 문자 발송에 실패했어요! | Send message: messages cannot be sent from this number right now. If it persists, contact KAT Cloud |
CH003 | 400 | 수신거부된 번호입니다. | The recipient has opted out |
CH004 | 400 | 제목이 너무 깁니다. (최대 64바이트) | subject exceeds 64 bytes (about 32 Korean characters) |
CH005 | 400 | 잘못된 커서 형식이에요. | Invalid cursor for GET /chat. Pass the value you received as is |
CH007 | 400 | 차단된 단어나 링크가 포함되어 발송할 수 없습니다. | The content contains a blocked word or link |
CR001 | 404 | 존재하지 않는 채팅방이에요! | The chat room does not exist or was left (deleted) |
CR002 | 400 | 잘못된 커서 형식이에요. | Invalid cursor for GET /chat-room |
CB001 | 402 | 크레딧 잔액이 부족하거나 자동충전에 실패했습니다. | Send chat. Check your credit on the console Billing page |
GR016 | 402 | 크레딧 잔액 부족으로 서비스가 차단되었습니다. 충전 후 이용 가능합니다. | Send message or chat. Check your credit on the console Billing page |
KC012 | 403 | 체험에 포함된 문자를 모두 사용했습니다. | See Authentication and group errors |
GL010 | 403 | 운영정책으로 인해 해당 기능이 제한되었습니다. | Sending messages is blocked by operating policy. Contact KAT Cloud |
GL007 | 415 | 지원하지 않는 파일유형입니다. | A non-image file in a media upload |
GL008 | 500 | 파일업로드에 실패했습니다. | Chat media upload failed. Upload again |
G400 | 400 | 업로드할 파일이 없습니다. / 업로드 가능한 파일이 없습니다. | Message media upload has no file, or no file could be uploaded |
G413 | 413 | File too large | The 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), andresultMessageis전달. - To tell whether a message reached the recipient, check whether
resultStatusis a success code, notsendStatus. - Codes not in the tables below have
resultMessageset toUnknown. 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
| resultStatus | Meaning |
|---|---|
4100 | Delivered |
4400 | No signal (shadow area) |
4401 | Handset powered off |
4402 | Handset message storage full |
4403 | Message deleted |
4404 | No subscriber location information |
4405 | Handset busy |
4410 | Invalid number |
4411 | NPDB error |
4412 | Call rejected by recipient |
4413 | SMSC format error |
4414 | Not a subscriber, unassigned number, or service suspended |
4415 | Identification code error |
4420 | Other error |
4421 | Timeout |
4422 | Handset temporarily suspended |
4423 | Handset rejected the message |
4424 | Handset does not support URL SMS |
4425 | Handset busy with a call |
4426 | Retry limit exceeded |
4427 | Other handset problem |
4428 | System error |
4430 | Spam |
4431 | Sending restricted: recipient opted out (spam) |
4432 | Callback number blocked (individual) |
4433 | Callback number blocked (business) |
4434 | Blocked: callback number not pre-registered |
4435 | Blocked: callback number reported as spam to KISA |
4436 | Callback number violates the pre-registration number rules |
4437 | Duplicate sending restricted |
4438 | Whitelist text check |
4443 | Blocked as spam by KISA |
LMS·MMS result codes
| resultStatus | Meaning |
|---|---|
6600 | Delivered |
6601 | Timeout |
6602 | Handset busy with a call |
6603 | No signal (shadow area) |
6604 | Handset powered off |
6605 | Handset message storage count exceeded |
6606 | Invalid number |
6607 | Service temporarily suspended |
6608 | Other handset problem |
6609 | Call rejected by recipient |
6610 | Other error |
6611 | Carrier SMC format error |
6612 | Gateway format error |
6613 | Handset does not support the service |
6614 | Handset cannot take calls |
6615 | Deleted by the SMC operator |
6616 | Carrier message queue exceeded |
6617 | Handled as spam by the carrier |
6618 | Handled as spam by the Fair Trade Commission |
6619 | Handled as spam by the gateway |
6620 | Sending count exceeded |
6621 | Message length exceeded |
6622 | Invalid number format |
6623 | Invalid data format |
6624 | MMS information not found |
6625 | NPDB error |
6626 | Recipient opted out via 080 (SPAM) |
6627 | Sending restricted: recipient opted out (SPAM) |
6628 | Callback number blocked (individual) |
6629 | Callback number blocked (business) |
6630 | Number not in service |
6631 | Blocked: callback number not pre-registered |
6632 | Blocked: callback number reported as spam to KISA |
6633 | Callback number violates the pre-registration number rules |
6670 | Attachment size exceeded (60K) |
Kakao result codes
Returned only for Kakao messages.
| resultStatus | Meaning |
|---|---|
7000 | Delivered |
7101 | Kakao format error |
7103 | Invalid sender key (sender profile key) |
7105 | Sender key (sender profile key) does not exist |
7106 | Sender key (sender profile key) deleted |
7107 | Sender key (sender profile key) blocked |
7108 | KakaoTalk channel blocked (check in the KakaoTalk channel admin tool) |
7109 | KakaoTalk channel closed (check in the KakaoTalk channel admin tool) |
7110 | KakaoTalk channel deleted (check in the KakaoTalk channel admin tool) |
7111 | KakaoTalk channel pending deletion (check in the KakaoTalk channel admin tool) |
7112 | Invalid business registration number |
7125 | KakaoTalk channel with messages blocked (check in the KakaoTalk channel admin tool) |
7203 | FriendTalk recipient is not a friend |
7204 | Template mismatch |
7300 | Other error |
7305 | Success uncertain (may be received within 30 days) |
7306 | Kakao system error |
7308 | Phone number error |
7311 | Message does not exist |
7314 | Message length exceeded |
7315 | No template |
7318 | Message cannot be sent |
7322 | Sending not allowed at this time |
7323 | Message group information not found |
7324 | Message to resend does not exist |
7325 | Variable length limit exceeded |
7326 | Chat/bot switch button text length limit exceeded |
7327 | Button/quick link content does not match the template |
7328 | Emphasized title does not match the template |
7329 | Emphasized title length limit exceeded (50 characters) |
7330 | Message type does not match the template's emphasis type |
7331 | Header does not match the template |
7332 | Header length limit exceeded (16 characters) |
7333 | Item highlight does not match the template |
7334 | Item highlight title length limit exceeded (30 characters without image, 21 with image) |
7335 | Item highlight description length limit exceeded (19 characters without image, 13 with image) |
7336 | Item list does not match the template |
7337 | Item description length limit exceeded in item list (23 characters) |
7338 | Item summary does not match the template |
7339 | Item summary description length limit exceeded (14 characters) |
7340 | Item summary description contains disallowed characters (anything other than currency symbols/codes, digits, commas, decimal points and spaces) |
7341 | Wide item list count does not match the min/max count |
7342 | Main link does not match the template |
7351 | Carousel item list count does not match the min/max count |
7352 | Carousel item message too long |
7421 | Timeout |
7521 | Duplicate 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
# 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.
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
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)
raiseRouting 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.
// 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;
}
}