# Telkit phone: a Korean 070 number for your voice agent > Telkit sells Korean 070 phone numbers. Incoming calls on a number go to one SIP address. Outgoing calls are SIP INVITEs that your own equipment (a LiveKit trunk or a PBX) sends to the Telkit SIP trunk. This file is a runbook for an AI agent. Follow the steps in order and make every API call yourself. Steps 1 to 6 are the setup run, and it ends when the first incoming call in step 6 is confirmed. Steps 7 to 11 are for when the person asks for them or a step sends you there. Stop where a step is marked (person), says "Not live yet" or tells you to wait for the person; tell the person what to do and continue when they are done. ## Rules for the whole run - API base URL: https://api.telkit.io. - Talk to the person in the person's language, in your own words. Keep identifiers, field names and error codes as they are. - Use only the operations named in this file, with the fields in the OpenAPI contract: https://telkit.io/openapi.json. Never invent endpoints, fields or values. - Besides the operations named in this file, you may follow one step that an authenticated API response offers in next_action (for example the response of GET /v1/workspace). Use only its method, path and body, and only when the person's request matches its purpose. Never mention or suggest it otherwise. If a response has no next_action, there is nothing to follow. - Create the first connection and poll/reissue its task without an Authorization header. Exchange its connect token using that token as Bearer, then use `Authorization: Bearer ` for all account operations and other human links. Never use an expired or unrelated bearer for a bootstrap request. Errors are always `{"error":{"code","message"}}`; branch on `code`. - On `401` the credential is missing, invalid, revoked or expired: check the correct credential for this operation; if it cannot be recovered, reconnect as in step 1 and resume. A one-time connect token must never be reused. On `429` wait for `Retry-After` seconds. Retry reads; before retrying a write after a timeout or an uncertain result, read the resource to confirm whether it succeeded. Never repeat a purchase, password rotation or payment blindly. On `503` tell the person the `message` and stop, except for `payment_pending` in step 4. - Business verification (the optional upgrade of a personal workspace to a business workspace) is for the workspace owner who is the business representative. Ask the person for the four values and a copy of the registration certificate, and copy the business name exactly as printed on it, character for character: parentheses, English text such as "(Fleek Inc.)" and the form of the company marker all count, and leading, trailing and repeated spaces are ignored. Never shorten, translate or tidy a value. - Steps marked "person" need the person. Tell them exactly what to do, wait until they say it is done, then read the state again with the API. Never claim a human step succeeded without the API showing it. - Never call a direct card-charge operation. Top-ups, payment retries and card registration happen on the person's own screen. Buying a number can charge its fee shortfall to a registered card: apply the explicit approval rule in step 3 before buying. - Take prices, credits and periods only from the pricing page and amounts only from API responses. Do not quote numbers from memory. The one exception is the sign-up credit: take its amount only from the credits section of https://telkit.io/docs/numbers/pricing.md, and if you cannot read it, say that credit is added once identity and a card are both done without giving a number. - A SIP password is shown once. Put it straight into the person's SIP equipment or secret store and do not repeat it in the conversation. The one exception: when the person must paste it into a voice-platform console themselves, give it to them exactly once in your reply, ask them to enter it right away, and never repeat it afterwards. - Telkit has no API that places a call. Your equipment sends the INVITE and ends the call with BYE. The per-number maximum call duration is the only limit Telkit applies to call length. - On the SIP trunk with digest auth, `From` and `P-Asserted-Identity` must each be the 070 number bound to the credential or that number's default caller ID. For an IP-allowlist-only number, `From` identifies the number, so it must be that number itself; only `P-Asserted-Identity` may carry its default caller ID. Anything else is rejected with `403` and `caller_id_not_allowed`. - For REFER transfers, start the call with the credential number in `From`. A dialog started with its default caller ID in `From` cannot use REFER (403); a successful transfer presents the credential number. ## Steps ### 1. Connect the person's account (person) - If you already hold this workspace's credential securely, verify it with `GET /v1/workspace` and continue to step 2. Otherwise call `POST /v1/connect-links` without Authorization and with JSON body `{"client":"My phone agent"}`. Save the entire `201` response securely, including `task_id`, `url`, `url_expires_at` and `task_expires_at`. Each POST creates a different task and does not support Idempotency-Key; do not create another while waiting. - Show only the returned `url` and its expiry to the person in your reply, not merely tool output. Ask them to open it and complete Google sign-in, your connection approval, phone identity verification. Later links that spend money ask for a 6-digit code sent by text message to that verified phone; an account that has not moved over yet may still see an authenticator app (TOTP) step. Card registration is not part of this gate; it comes before buying a number. Never complete these steps or approve for them. - Poll `GET /v1/human-tasks/{id}` with the saved task_id and no Authorization, once every 5 seconds for up to 5 minutes. Keep each full response securely until you have inspected its `result`; never pipe away the body or run competing pollers. `pending` means wait. If it is still pending after 5 minutes, stop polling and tell the person to finish the page and come back to you; resume polling the same task when they do. The task lasts 7 days. The task ID is a secret capability: never print it or put it in logs. - If its 1-hour URL has expired while the task is still pending, call `POST /v1/human-tasks/{id}/link` for the same task_id and give the new URL to the person; this invalidates the previous URL and does not extend the task deadline. `expired` requires a new first connection; `canceled` means the task was closed before it finished: the person stopped or rejected it, a newer link replaced it, or you canceled it. Stop, and restart only when they ask. To withdraw a link the person should no longer use, call `POST /v1/human-tasks/{id}/cancel` with the same credential you poll it with: `200` returns the task with status `canceled` and its link stops working. `409` with `human_task_closed` means it was already completed, expired, canceled or approved by the person, so there is nothing to cancel; read the task again. Do not reissue a completed task. - On `completed`, save `result.connect_token` immediately: it is returned only once, and later polls return null. Exchange it once with `POST /v1/api-keys`, `Authorization: Bearer `, and JSON body `{"name":"My phone agent"}`. Store the `201` response's `secret` straight into a secret store, never into chat or logs, and keep its `id` with it: revoking the key needs that `id`. Use that secret as Bearer for the remaining steps, then verify `GET /v1/workspace`. If a one-time response was lost or the exchange result is uncertain and no secret was saved, do not repeat the exchange; start a new first connection with the person. Their existing workspace is reused without another signup credit. - These routes require the first-connect feature to be enabled on both API and human web page. On `503 not_available`, or if the returned page is unavailable, tell the person the service is not enabled and stop; never guess another URL or silently switch to the old console. - Calls: `POST /v1/connect-links`, `GET /v1/human-tasks/{id}`, `POST /v1/human-tasks/{id}/link`, `POST /v1/human-tasks/{id}/cancel`, `POST /v1/api-keys`, `GET /v1/workspace` ### 2. Confirm identity and consent (agent) - Read `GET /v1/workspace` and `GET /v1/me`. Continue only when `identity_verified` and `consents_current` are true; the personal workspace has `auth_tier` personal and `number_limit` 1. The person completes identity and terms on their own first-connect page; you never call `POST /v1/identity/verify` or `POST /v1/consents`. - If a required identity check fails, return to the human first-connect flow in step 1. If a second-factor check is the blocker (`mfa_required`), use the `error.next_action` link described under `mfa_required` in step 4 instead. If current terms are still not confirmed after that flow, pause for support rather than recording consent yourself. The API is the confirmation; a person saying they clicked is not proof that the account is ready. - Calls: `GET /v1/workspace`, `GET /v1/me` ### 3. Check the balance (agent) - Read `GET /v1/billing/balance`. Credit (`credit_krw`) is spent before charged balance (`charged_krw`); `available_krw` is what you can use now. The sign-up credit arrives once the conditions on the pricing page are met. - If `register_card_recommended` is true, no card is on file and buying a number in step 4 is refused with `card_required` whatever the balance. Give the card notice below in your first reply to the person after this read, together with anything else you ask them then (for example the SIP address in step 4), and give it once in the whole run: step 4 adds it only if you have not said it yet. Say, in the person's language, filling only with the amount read from the credits section of https://telkit.io/docs/numbers/pricing.md: "Buying a number needs a registered card, even if your balance would cover the fee. Once your identity is verified and a card is registered, Telkit adds of credit once per person; if you already received it, registering again adds nothing. Calls and other fees are still paid from your balance. Tell me if you want the link." The signal only says that no card is active, not that the credit is still available to this person, so never promise it as certain. If you cannot read the amount, follow the sign-up credit exception in the rules and give no number. If they choose to register, call `POST /v1/payment-methods/session` with the workspace secret from step 1; `201` returns a human link, not a charge. Hand its `url` to them and poll `GET /v1/human-tasks/{id}` with your workspace Bearer using the pending/expiry rules in step 1. Only they open the card window. A `200` browser payment response is not a human link: stop rather than processing it yourself. After completion read `GET /v1/billing/balance` again. On unavailable card configuration, explain that card registration is unavailable and stop before buying: a number cannot be bought without a card. - Immediately before buying, read `GET /v1/billing/balance` again. If `register_card_recommended` is true, do not buy: go back to the card notice above. If it is false, a card is on file. When `available_krw` is below the number fee on the pricing page, buying in step 4 charges a shortfall to that card. Compute `usable = min(max(available_krw, 0), number_fee_krw)`, `shortfall = number_fee_krw - usable`, and `card_total = shortfall + floor(shortfall / 10)` in integer KRW. Negative balance does not increase this purchase charge. Show the shortfall and the VAT-inclusive card amount in the purchase explanation in step 4, warn that intervening usage can change the final amount, and buy only after they explicitly agree. If they do not agree, stop before buying. Repeat this check before every new purchase attempt. - Calls: `GET /v1/billing/balance`, `POST /v1/payment-methods/session`, `GET /v1/human-tasks/{id}`, `POST /v1/human-tasks/{id}/link` ### 4. Buy one 070 number (agent) - Read `GET /v1/numbers`. A personal account holds one 070 number in this release. If it already has one, read `GET /v1/numbers/{id}` before continuing: a pending purchase also appears in the list. If `next_billing_at` equals `issued_at`, follow the payment_pending wait below without repeating the purchase. If it is suspended, has an overdue or missing billing date, or is not usable, go to step 9 and stop setup. Only a paid usable number proceeds to step 5; never buy a replacement just because setup is paused. - Before buying a new number, ask the person for the SIP address of the voice agent or PBX that will answer its calls, for example `sip:proj_@sip.api.openai.com` for an OpenAI project; step 5 saves it. Telkit does not answer calls itself: it forwards them to that address. If they have none yet, do not buy and do not invent an address. Say, in the person's language: "A Telkit number forwards calls to your own voice agent, so I will buy one once yours is ready. Tell me its SIP address then. If you want to hear what a phone agent sounds like first, open https://telkit.io/#demo and request a demo call to your own mobile." Stop here and resume at this step when they give you an address. The demo is the person's own action on that page, so never request it for them. It needs a Korean internet connection, runs only during daytime hours in Korea, and does not test a Telkit number. - Find numbers with `GET /v1/numbers/available` (`limit=5`). Let the person pick one, or pick the first if they leave the choice to you. - Before `POST /v1/numbers`, always explain the purchase and wait for the person's explicit yes, even when they asked you to buy a number. The API does not return prices: take the number fee and the call rates from the pricing page, and the balance from `GET /v1/billing/balance` read right before (step 3). Say, in the person's language, filling in only those values: "I picked . It costs a month before VAT and renews every 30 days. It is paid from your Telkit balance, credit first and then charged balance, and you have available now. Calls are charged to the same balance after each call: before VAT for incoming calls, and the outgoing rates are on the pricing page. If you cancel, you keep the number until the paid period ends and the fee is not refunded. Shall I buy it?" When step 3 found a card shortfall, add the shortfall and the VAT-inclusive card amount before the question. Do not ask this question while `register_card_recommended` is true: the card comes first (step 3). Buy only after they say yes, with `POST /v1/numbers` and body `{"number_id":""}`; if they decline, stop before buying. Explain and ask again before every new purchase attempt. `201` means bought; `200` means it was already yours. - On `403` with `identity_required` or `consent_required`, go back to step 2. On `403` with `mfa_required`, the account still has to pass its second factor for this action. The error carries `error.next_action` of type `human_task` (kind `top_up` or `card_registration`) with a signed `url`: hand that link to the person. It leads them to verify their identity again when it is asked for, or to enter a 6-digit code sent by text message to the verified phone (accounts not yet moved over still get the authenticator app (TOTP) step there). The link may also show a top-up form; the person does not have to top up. Do not wait for the task to complete: when the person says they finished entering the code, retry the same request. The first-connect flow has no separate second-factor step for accounts on text-message codes, so do not send the person back to step 1 for this. On `409` with `number_limit_reached`, the workspace already has as many numbers as its limit allows (a personal workspace may own one): read `GET /v1/numbers` again. A purchase that needs a card payment for the shortfall holds the response while the card is charged, so it can take longer than other requests: wait for the response and do not send it twice. On `402` with `payment_failed` the card payment failed: nothing was bought, nothing was charged and the number was released. `error.next_action` is a `human_task` of kind `card_registration` with a signed `url` where the person changes the card; hand it to the person, poll `GET /v1/human-tasks/{id}` as in step 3, and buy the number again only after the card is changed and the person says yes. On `payment_pending` (`503` or `409`) the card payment is still being settled and the number is not paid yet, even though `GET /v1/numbers` already shows it: do not repeat `POST /v1/numbers`. Wait a minute and read `GET /v1/numbers/{id}`. It is paid once `next_billing_at` is 30 days after `issued_at`; while the two are equal it is still pending, so read again once a minute for up to 5 minutes. If it is still pending, tell the person and pause; resume by reading the same number, never by creating another purchase. A `404` with `number_not_found` after `payment_pending` means the payment failed later and the number was released; nothing was charged. Tell the person, and if they still want that number send `POST /v1/numbers` for it once more: a second failure answers `payment_failed` with the card link. On `402` with `card_required` no card is on file, whatever the balance: nothing was bought and nothing was charged. When first connect is enabled, `error.next_action` is a `human_task` of kind `card_registration` with a signed `url`; hand it to the person and poll `GET /v1/human-tasks/{id}` as in step 3, then read `GET /v1/billing/balance` again and retry once the card is registered. On `409` with `number_unavailable`, pick another number. - Read `GET /v1/numbers/{id}`. The number fee renews every 30 days from the purchase time (`next_billing_at`). Tell the person the number in its `display` form and go straight on to step 5: buying is not the end of setup. Say, in the person's language: "Your Telkit number is . Next I will connect it to your voice agent, and then you will test it with one call from your mobile." - Calls: `GET /v1/numbers`, `GET /v1/numbers/available`, `POST /v1/numbers`, `GET /v1/numbers/{id}`, `GET /v1/billing/balance` ### 5. Send incoming calls to the person's agent (agent) - Save the SIP address the person gave you in step 4 with `PUT /v1/numbers/{id}/connection` and body `{"sip_uri":"
"}`. TLS with SRTP is the default; see the First call page and the guide for their platform for other transports and options. If the number was bought earlier and you do not have its address, ask the person for it now; if they have none yet, tell them the number refuses calls until it is connected, stop, and resume at this step when they give you one. - On `422` show the person the `code` and ask for a reachable address. Keep the `200` response's `updated_at` privately. Routing follows a new address within about a minute and a call placed before that is refused with `486`, so start step 6 only 60 seconds after `updated_at`. The receiving side must accept incoming calls for this number: the receiving PBX or voice agent platform must accept calls from the Telkit source addresses `34.64.81.145` and `34.47.68.103` (allow both; signaling uses TLS on port 5061 or UDP and TCP on port 5080, audio uses RTP on UDP 30000 to 40000), because Telkit does not send a username or password on forwarded calls, and an OpenAI project must be set up as on the OpenAI page. - Calls: `PUT /v1/numbers/{id}/connection` ### 6. First incoming call (person) - Record the test start time, expected inbound direction and calling number privately. Say, in the person's language: "Please call from your mobile now. Your voice agent should answer. End the call after a few seconds and tell me when you have." Save the equipment's `telkit_call_id` when available. - About 30 seconds after the call ends, read `GET /v1/numbers/{id}/calls` (`limit=5`). Match the record by `telkit_call_id` when available; otherwise require the test time window, direction and `peer_e164` to match uniquely. Never treat the newest row alone as the test result. Read every returned page needed to cover that time window. If no unique matching record exists, read again every 30 seconds for up to 5 minutes, then report that the test is unverified and use the Troubleshooting page. Only for the matching record show direction, duration and `charge_krw`; if it was not answered, use its `sip_code` and `result_text`. `GET /v1/calls/{telkit_call_id}` returns one call by its `telkit_call_id`. - If the matching record has `answered_at`, that was the number's first call. Compute the time from the number's `issued_at` in `GET /v1/numbers/{id}` to `answered_at`, in minutes or in hours when longer, and say: "Your first call connected,