Getting started

Quickstart

From signup to a call with your own voice agent in five minutes. Every step is one command - copy, paste, run.

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 SMS and calls. 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.

2Create your API key

In the portal, open API and MCP and click Create key. The key looks like vk_... and is shown only once - we store only a hash of it, so we can't show it back to you later either. Copy it right away.

3Connect - MCP or REST API

Pick one, or use both. For work inside an AI editor, MCP is fastest - the editor discovers all 31 tools by itself and calls them when it makes sense in the conversation. For your own app, reach for the REST API directly.

Option A - MCP server

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 volai https://volai.cz/mcp \
  --header "Authorization: Bearer vk_YOUR_KEY"

Option B - REST API (curl)

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"
}

4Get a 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 "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"
}

5Send your first SMS

Send a text to any Czech or Slovak number (the MVP supports only these two). Don't wait for a reply through the API though - the carrier delivers inbound SMS straight to the SIM card, not to us:

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

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

6Buy a number and set up a voice agent

First, a number from the free pool - an empty body {} assigns you whichever number is free:

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

{
  "number": {
    "e164": "+420601234567",
    "routing": { "mode": "none" },
    "monthlyFeeHal": 2500,
    "boughtAt": 1756111640000
  }
}

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 "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": "+420601234567"
  }'

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