Getting started

Quickstart

Connect your AI assistant or app and verify access without placing a call. Then continue with the work you need: invoices, appointments, SMS, incoming calls or a custom task.

1Create an account

Signup takes a minute, it's free, and you don't need a card. Once you verify your email, 50.00 CZK (~EUR 2.08) of credit lands on your account - enough to buy a number and run a few test calls (SMS require a first top-up). If you forget your password, you can reset it anytime from a link on the login page - a regular email with a link to set a new one.

2Open assistant access

In the portal, open AI assistant and choose OAuth. Claude Code, Codex CLI and Codex desktop can open sign-in; other clients can use the existing API-key fallback.

3Connect - MCP or REST API

MCP puts volai tools directly in your assistant. REST API fits your own app. Both use the same account and key; supported actions and their limits are listed in the capability map below.

AI assistant over MCP

One command for Claude Code (installation for Cursor, Windsurf, VS Code and Claude Desktop is on the MCP server page):

claude mcp add --transport http --scope user volai 'https://volai.cz/mcp'
claude mcp login volai

Verify access without placing a call

Paste this prompt into a new chat in your connected assistant. Access is complete only after it actually reads through `get_balance` and `list_agents`; verification does not require a call, SMS or number purchase.

Connect volai as an MCP server at https://volai.cz/mcp using the guide at https://volai.cz/SKILL.md. If it is already connected, use the existing connection. If you can manage MCP in this environment, prepare the configuration; otherwise guide me through the specific steps. Use sign-in through volai, and leave sign-in and consent to me. Do not ask for an API key in chat. Then verify the connection using get_balance and list_agents. Change nothing else, make no calls, send no messages and buy nothing.

Your own app over REST API

Verify the key with a single query for your credit balance:

curl https://volai.cz/v1/balance \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "balanceHal": 5000,
  "balanceCzk": 50.00,
  "currency": "CZK"
}

4Optional: choose what comes next

After verification, follow your actual goal. Use the guide, the full web portal, REST API or your own MCP prompt; the examples below are inspiration, not a mandatory first task.

Replace example numbers and IDs with your own. Responses below show the relevant fields; the REST reference has the full shapes. Reuse the same Idempotency-Key when retrying a paid action; use a new key for a new action.

Optional: try the voice in a real call

This is the fastest way to hear volai for yourself: one request, and your phone rings a few seconds later. No number to buy, no agent to set up - just write what the agent should do into systemPrompt instead of agentId. The call comes from volai's shared demo number.

curl -X POST https://volai.cz/v1/calls \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Idempotency-Key: REPLACE_WITH_UNIQUE_CALL_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+420777123456",
    "systemPrompt": "You are the receptionist at Cafe Zero. Greet the caller, ask what they want, and repeat the order back."
  }'

{
  "id": "c_8f2ac1d4x7qz",
  "status": "initiated",
  "trial": true,
  "from": "+420266266641"
}

Optional: send an SMS

Send a text to any Czech or Slovak mobile number (we do not send SMS to other countries). SMS require a first credit top-up - the welcome credit does not cover them. Don't wait for a reply though - recipients cannot reply to the shared sender name SMSinfo, and volai voice numbers do not receive SMS (receiving SMS and sending from your own number is what the SMS number add-on does - see the SMS numbers section of the API reference):

curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Idempotency-Key: REPLACE_WITH_UNIQUE_SMS_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456", "body": "Hello from volai! - My App"}'

{
  "id": "msg_7c1f9a2e",
  "status": "sent",
  "priceHal": 136,
  "segments": 1
}

Optional: get a number for incoming calls

First, a number from the free pool - an empty body {} assigns a number from the default Prague offer. Set region for another offer, or choose an e164 from GET /v1/numbers/available. Buying immediately charges the first billing period:

curl -X POST https://volai.cz/v1/numbers \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Idempotency-Key: REPLACE_WITH_UNIQUE_NUMBER_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "number": {
    "e164": "+420210123456",
    "routing": { "mode": "none", "hasSipPassword": false },
    "monthlyFeeHal": 2500,
    "boughtAt": 1756111640000,
    "region": "praha",
    "regionLabel": "Prague",
    "billingMonths": 1
  }
}

Now attach an agent to that number - just a name, a system prompt, and the number from the step above:

curl -X POST https://volai.cz/v1/agents \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Idempotency-Key: REPLACE_WITH_UNIQUE_AGENT_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Receptionist",
    "systemPrompt": "You are the receptionist at Cafe Zero. You take pickup orders and answer questions about opening hours (8am-6pm, Mon-Fri). Never invent a price you do not know. End the call by summarizing the order.",
    "numberE164": "+420210123456"
  }'

{
  "id": "ag_kx91fa2b"
}

That's it - call your new number. The agent should pick up within a few seconds and speak exactly as you wrote in systemPrompt.

Capability map

Browse the areas and available features. REST and MCP counts show covered features eligible for each interface. The reference explains intentional exceptions, such as creating access only in the portal.

The full list is in the REST API reference and in the tool list on the MCP page.