Primeiros passos

Início rápido

Ligue o seu assistente de IA ou a sua aplicação e verifique o acesso sem fazer uma chamada. Depois continue com o trabalho de que precisa: faturas, marcações, SMS, chamadas recebidas ou uma tarefa própria.

1Criar uma conta

O registo demora um minuto, é gratuito e não precisa de cartão. Depois de confirmar o seu e-mail, 50.00 CZK (~EUR 2.08) de saldo ficam na sua conta - o suficiente para comprar um número e fazer algumas chamadas de teste (as SMS exigem um primeiro carregamento). Se se esquecer da palavra-passe, pode repô-la a qualquer momento a partir de uma ligação na página de início de sessão - um e-mail normal com uma ligação para definir uma nova.

2Abrir o acesso do assistente

No portal, abra Assistente de IA e escolha OAuth. O Claude Code, o Codex CLI e o Codex desktop podem abrir o início de sessão; os outros clientes podem usar a alternativa existente com chave de API.

3Ligar - MCP ou API REST

O MCP coloca as ferramentas da volai diretamente no seu assistente. A API REST serve para a sua própria aplicação. Ambos usam a mesma conta e a mesma chave; as ações suportadas e os seus limites constam do mapa de funcionalidades abaixo.

Assistente de IA através do MCP

Um comando para o Claude Code (a instalação para o Cursor, o Windsurf, o VS Code e o Claude Desktop está na página do servidor MCP):

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

Verifique o acesso sem fazer uma chamada

Cole este prompt numa nova conversa no seu assistente ligado. O acesso só está completo depois de ler efetivamente `get_balance` e `list_agents`; a verificação não exige uma chamada, uma SMS nem a compra de um número.

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.

A sua própria aplicação através da API REST

Verifique a chave com um único pedido do seu saldo:

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

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

4Opcional: escolha o que vem a seguir

Após a verificação, siga o seu objetivo real. Use o guia, o portal web completo, a API REST ou o seu próprio prompt MCP; os exemplos abaixo servem de inspiração, não são uma primeira tarefa obrigatória.

Substitua os números e identificadores de exemplo pelos seus. As respostas abaixo mostram os campos relevantes; a referência REST tem as estruturas completas. Reutilize o mesmo Idempotency-Key ao repetir uma ação paga; use uma nova chave para uma nova ação.

Opcional: experimente a voz numa chamada real

É a forma mais rápida de ouvir a volai por si próprio: um pedido e, poucos segundos depois, o seu telefone toca. Sem número para comprar, sem agente para configurar - basta escrever o que o agente deve fazer em systemPrompt em vez de agentId. A chamada parte do número de demonstração partilhado da volai.

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": "Voce e o rececionista do Cafe Zero. Cumprimente quem liga, pergunte o que deseja e repita o pedido no fim."
  }'

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

Opcional: enviar uma SMS

Envie uma mensagem para qualquer número móvel checo ou eslovaco (não enviamos SMS para outros países). As SMS exigem um primeiro carregamento de saldo - o saldo de boas-vindas não as cobre. Não espere, porém, uma resposta - os destinatários não podem responder ao nome de remetente partilhado SMSinfo e os números de voz da volai não recebem SMS (receber SMS e enviar a partir de um número próprio é o que fazem o complemento número de telemóvel e número para chamadas e SMS - veja as secções Números de telemóvel e Número para chamadas e SMS da referência da API):

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": "Olá da volai! - A Minha Aplicação"}'

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

Opcional: obter um número para chamadas recebidas

Primeiro, um número da reserva livre - um corpo vazio {} atribui um número da oferta de Praga predefinida. Defina region para outra oferta, ou escolha um e164 de GET /v1/numbers/available. A compra cobra de imediato o primeiro período de faturação:

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

Agora associe um agente a esse número - basta um nome, um prompt de sistema e o número do passo anterior:

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": "Rececionista",
    "systemPrompt": "Voce e o rececionista do Cafe Zero. Aceita encomendas para levantamento e responde a perguntas sobre o horario (8h-18h, seg-sex). Nunca invente um preco que nao conheca. Termine a chamada resumindo a encomenda.",
    "numberE164": "+420210123456"
  }'

{
  "id": "ag_kx91fa2b"
}

É tudo - ligue para o seu novo número. O agente deve atender em poucos segundos e falar exatamente como escreveu em systemPrompt.

Mapa de funcionalidades

Explore as áreas e as funcionalidades disponíveis. As contagens REST e MCP mostram as funcionalidades cobertas elegíveis para cada interface. A referência explica as exceções intencionais, como a criação de acessos apenas no portal.

A lista completa está na referência da API REST e na lista de ferramentas da página MCP .