Place calls from your own assistant or code

Your Zvani workspace is reachable as an MCP server and as a REST API. An AI assistant such as Claude can ring a number with one of your agents, wait for the conversation to end, and read back what was said and decided. A script or a CRM can do the same over plain HTTP.

Quick start

1. Get a key. A workspace owner or admin opens the Zvani web app, goes to Members → API keys and creates a key with the read and place_calls scopes. It is shown once and looks like zv_….
2. Connect your assistant. In Claude Code:
   shell

   claude mcp add --transport http zvani https://zvani.lv/api/v1/mcp \
     --header "Authorization: Bearer zv_..."

   Other clients are below.
3. Ask for a call. For example: “Using Zvani, call +371 2000 0000 with the purchasing agent and ask whether part 123456789 is in stock. Tell me what they said.” The assistant looks up the agent, places the call, waits for it and reports the outcome.

API keys

A key belongs to one workspace and acts on that workspace only. It is stored hashed, can be revoked at any time in the same screen, and is shown in full only when created. Treat it like a password: keep it out of source code and chat logs.

A workspace holds at most 20 live keys; revoke the ones you no longer use. A key belongs to the workspace, not to the person who made it: it keeps working when that person leaves, because the integration it serves is the workspace's. Revoke it from the same screen if that is not what you want. A key of a suspended workspace answers 403 workspace_suspended until the workspace is active again.

Send the key in either header:

Authorization: Bearer zv_...
x-api-key: zv_...

Connect over MCP

The server speaks Streamable HTTP and is stateless: there is no session to keep, and a client can reconnect at any time. The tools it offers follow the key's scopes: a read key sees the read tools, a place_calls key also sees calls_place.

Claude Code

claude mcp add --transport http zvani https://zvani.lv/api/v1/mcp \
  --header "Authorization: Bearer zv_..."

Clients configured with JSON

Clients that accept a remote server URL with headers (Cursor, Windsurf, VS Code and others) take an entry like this in their MCP configuration file:

{
  "mcpServers": {
    "zvani": {
      "url": "https://zvani.lv/api/v1/mcp",
      "headers": { "Authorization": "Bearer zv_..." }
    }
  }
}

Clients that only run local servers

Claude Desktop's configuration file and other clients that start a local process can reach the server through the mcp-remote bridge (needs Node.js):

{
  "mcpServers": {
    "zvani": {
      "command": "npx",
      "args": [
        "mcp-remote", "https://zvani.lv/api/v1/mcp",
        "--header", "Authorization:${ZVANI_AUTH}"
      ],
      "env": { "ZVANI_AUTH": "Bearer zv_..." }
    }
  }
}

Check the connection

Ask the assistant to call me_get. It answers with the workspace the key belongs to and its scopes. If calls_place is missing from the tool list, the key has no place_calls scope.

Placing a call

An agent's prompt can contain {placeholders} — facts it needs for this particular call, such as a part number or a company name. The caller fills them when placing the call.

1. agents_list — find the agent to call with. Outbound agents have direction: "outbound".
2. agents_get — read its placeholders: these are the keys variables should carry. Its spokenLanguage is the language it opens the call in.
3. calls_place — ring the number. It answers at once with a placementId; the call itself is only starting.
4. calls_wait — pass the placementId. Each request waits up to timeoutSeconds for the call to end and be analysed; call it again until status is done, not_reached or failed.

calls_place arguments

The answer's status is calling when the dial went out, or queued when the schedule is holding it. The finer states below come from calls_wait.

Placement status

Reading the result

At done, calls_wait returns the call. The fields you will usually want:

Transcripts and recordings are not part of the API. They are in the Zvani web app.

Tools

Every tool is also a REST endpoint; tool names are operation ids with _ in place of ..

The same over REST

All paths are under https://zvani.lv/api/v1, bodies and answers are JSON.

1. Read the agent

curl https://zvani.lv/api/v1/agents \
  -H "Authorization: Bearer $ZVANI_KEY"

2. Place the call

curl -X POST https://zvani.lv/api/v1/calls/place \
  -H "Authorization: Bearer $ZVANI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "toNumber": "+37120000000",
    "agentId": "ag_...",
    "variables": { "part_number": "123456789" },
    "name": "Jonas"
  }'

Answers 202 (status is calling or queued):

{
  "placementId": "camp_...",
  "status": "calling",
  "agentId": "ag_...",
  "toNumber": "+37120000000",
  "unfilled": []
}

3. Wait for the result

curl -X POST https://zvani.lv/api/v1/calls/wait \
  -H "Authorization: Bearer $ZVANI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "placementId": "camp_...", "timeoutSeconds": 60 }'

{
  "placementId": "camp_...",
  "status": "done",
  "call": {
    "id": "lead_...",
    "status": "completed_action",
    "durationSeconds": 74,
    "summary": "...",
    "outcome": { /* fields of the agent's outcome tool */ },
    "outcomeSource": "agent"
  }
}

Repeat step 3 while status is not done, not_reached or failed.

Errors

Every error has the same shape: a stable code, a hint written to be read by a person or an AI, and sometimes details.

{
  "error": "agent_required",
  "hint": "this workspace has several agents; name one with agentId",
  "details": { "agents": [ /* id, name, direction */ ] }
}

Limits and cost

• 120 requests per minute per key. Above that the answer is 429 with Retry-After.
• Calls cost minutes. Each placed call is billed to the workspace like any other call. A key with place_calls can spend them; give it only to programs you trust.
• One attempt per placement. A call that is not answered is not retried; place it again if you want another try.
• Don't poll for new calls. To react to calls as they finish, subscribe a webhook instead.

Webhooks

To hear about calls as they finish, subscribe a URL. Every finished call that raises one of the events you chose is POSTed to it once its summary is ready. Subscriptions are what the Zapier, Make and n8n apps use; a script of your own can use them the same way with a key that has the read scope.

curl -X POST https://zvani.lv/api/v1/webhooks \
  -H "Authorization: Bearer $ZVANI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks/zvani", "events": ["call.completed", "call.needs_callback"] }'

The answer carries the subscription's id and its secret, shown only this once. Subscribing the same URL again with the same key answers the same subscription (with the events you name now) rather than a second one, so a workflow switched off and on does not double its deliveries. The events:

• call.completed — every call, once its summary, score and outcome are ready (at once, where the workspace has no post-call analysis);
• call.needs_callback — the caller asked to be called back;
• call.transferred — the call was handed to a person;
• campaign.finished — an outbound campaign has no contacts left to ring; the delivery carries campaign instead of call;
• lead.updated, booking.created, order_request.created, sms.sent — a finished call's record changed afterwards (marked reviewed, its callback done), the agent booked an appointment, wrote down an order request, or sent the caller a text. Delivered as they happen: a booking or a text during the call, an order request when it is taken, and a call's record each time it changes.

Each delivery is {"event", "deliveredAt", "call"}, where call has the shape of GET /calls/{id} (campaign.* carries campaign, the shape of GET /campaigns/{id}). It comes with X-Zvani-Event, X-Zvani-Timestamp — milliseconds since the epoch — and X-Zvani-Signature: the hex HMAC-SHA256 of timestamp + "." + body with the secret. Check it before you trust the body, and refuse a timestamp more than a few minutes old: a captured delivery cannot then be replayed later. X-Zvani-Event-Id names the event (the same across retries and across your subscriptions) and X-Zvani-Delivery-Id this one delivery; keep the event ids you have handled and drop a repeat, because a delivery is made at least once, not exactly once.

import { createHmac, timingSafeEqual } from 'node:crypto';

function fromZvani(rawBody, headers, secret) {
  const expected = createHmac('sha256', secret)
    .update(`${headers['x-zvani-timestamp']}.${rawBody}`)
    .digest('hex');
  const got = Buffer.from(String(headers['x-zvani-signature'] ?? ''));
  const fresh = Math.abs(Date.now() - Number(headers['x-zvani-timestamp'])) < 5 * 60 * 1000;
  return fresh && got.length === expected.length && timingSafeEqual(got, Buffer.from(expected));
}

Answer 2xx quickly and do the work afterwards. A timeout, a 408, a 429, a 5xx or no answer is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, then given up; any other 3xx or 4xx is final — a redirect is not followed. Answer 410 and the subscription is removed. A subscription whose deliveries have all failed for a day is switched off (disabledAt in GET /webhooks); subscribing the URL again switches it back on. GET /webhooks lists the subscriptions this key made (an owner or admin signed in to the web app sees the whole workspace's) and DELETE /webhooks/{id} removes one. URLs must be public https.

The webhook module in the web app is a different, older thing: one URL typed into the panel, which receives a flat JSON object per finished call — event, leadId, callerPhone, direction, status, durationSeconds, summary, score and so on — signed the same way, with three in-process attempts. New integrations should subscribe through the API.

Shop and website plugins

Ready plugins give the agent a shop's orders, products and delivery prices during the call, over MCP, and keep the pages you choose in the knowledge base through PUT /knowledge/pages/{externalId} with a key of the knowledge scope: WordPress and WooCommerce and OpenCart. Every integration is listed on zvani.lv/integrations.

A whole website as a source

Without a plugin, give the site's address once and Zvani finds its pages itself: through robots.txt and the sitemaps it names (or /sitemap.xml), or, when there is none, by following links from the start page three deep within the site. Every page with enough text becomes a document the agent answers from; the first sync starts at once, and the site is read again daily or weekly. A later sync reads only pages whose sitemap date or text changed, and takes out pages the site no longer lists. Disallow rules in robots.txt are honoured, requests are paced to two a second, and a page's title and address are kept with its text. Same key scope, knowledge; up to three sites per workspace.

POST /api/v1/knowledge/sites
{
  "url": "https://www.yourshop.lv",      // https only, a public address
  "include": "/help\n/delivery",     // optional: keep only paths starting with these, one per line
  "exclude": "/blog",               // optional: leave these out
  "frequency": "weekly"              // or "daily"; weekly when omitted
}

201
{
  "id": "kbs_...", "url": "https://www.yourshop.lv/", "include": "/help\n/delivery", "exclude": "/blog",
  "frequency": "weekly", "maxPages": 100, "status": "idle", "pages": 0, "createdAt": "..."
}

Once a sync has run, the same object also carries lastStartedAt, lastFinishedAt, nextRunAt and lastResult — { found, added, updated, unchanged, removed, skipped, failed, error? } — and pages says how many of its pages are in the knowledge base now. status is idle, running or failed; a failed sync keeps its counts and puts the reason in lastResult.error, and is tried again within the hour.

maxPages is how many pages a site may keep on the workspace's plan: 20 on Free, 100 on Starter, 300 on Business, 1000 on Corporate. Pages found beyond that are counted as skipped. The errors these operations add to the common ones:

n8n, Make, Zapier

The n8n community node is ready for self-hosted n8n; the Zapier and Make apps are coming. They give you, without writing code: a trigger when a call finishes (or needs a callback, or went to a person), actions to place a call and request a callback, and searches for a call or a phone number's history. Until the Zapier and Make apps are listed, you can use the pieces they are built from:

• n8n — the MCP Client Tool node in an AI Agent workflow: endpoint https://zvani.lv/api/v1/mcp, transport HTTP Streamable, authentication Bearer Auth with your key; every tool on this page appears in the agent's toolbox. For a trigger, a Webhook node whose production URL you subscribe.
• Make and Zapier — their HTTP modules with the same key for the REST operations, and a custom webhook (Make) or Catch Hook (Zapier) whose URL you subscribe.

Reference

• OpenAPI 3.1 document — every public operation with its full input and output schemas. Opens in Swagger Editor, Postman or Insomnia, and works as a tool definition for AI frameworks.
• Discovery — a JSON list of the operations and how to authenticate, readable without a key.

Questions: info@zvani.lv