Documentation

To go from nothing to a voice agent taking calls, work through the steps in order. Most of it happens in the dashboard — no code needed.

1. 1

   Create your account and workspace

   Sign up, name your workspace, and invite your team. One workspace holds your agents, numbers, widgets and call history.

2. 2

   Connect your carrier, models and keys

   Add your Twilio account for phone numbers. Pick Gemini, the default language model, or bring your own Ollama model. For speech to text use Whisper or Groq, and for text to speech use Kokoro or ElevenLabs. Your keys stay in your workspace.

3. 3

   Create an agent

   Start from a single prompt or one of 50 templates, add a knowledge base, and pick a voice. The agent follows the prompt literally, so write it the way you would brief a new hire.

4. 4

   Test it in the playground

   Talk to the agent in text and voice, read the transcript, and fix the prompt before anyone real hears it.

5. 5

   Connect a phone number, a widget, or both

   Give the agent a Twilio number so it can take calls, or add the website widget to any page with one script tag. Either way, the conversation lands in your dashboard like any other call.

6. 6

   Go live and watch the first calls

   Set a fallback for calls the agent cannot handle, then watch the first real calls, transcripts and recordings land in your dashboard.

Every Callingtap agent runs on four layers. You pick the provider for each layer when you build the agent, and you can change a provider without rebuilding the agent.

1. 1

   Telephony

   The call arrives by phone number, or from the website widget on your page.

2. 2

   Speech to text

   What the caller says is transcribed as they talk — Whisper on your own server, or Groq as a hosted option.

3. 3

   LLM

   The model picks the reply, using your prompt, your knowledge base and your integrations. Gemini is the default. Ollama runs the model on your own server.

4. 4

   Text to speech

   The reply streams back to the caller as audio — ElevenLabs, or Kokoro on your own server.

The recording, transcript and cost of each call land in your dashboard, whether the call came in by phone or by widget.

A Callingtap agent answers the phone and chats on your website. You build it in the dashboard — no code needed — from a single prompt, from a conversation flow, or from a template.

Callingtap does not run the stack for you. You connect the pieces, and they run on your server or on the hosted plan you choose:

• Telephony: your own Twilio account, or your own SIP trunk.
• Language model: Gemini is the default, or bring your own Ollama model.
• Speech to text: Whisper, or Groq.
• Text to speech: ElevenLabs, or Kokoro.

Create your first agent

1. 1

   Open Dashboard → Agents → Create

   Give the agent a name and a job. A name like receptionist for a dental clinic beats a blank prompt.

2. 2

   Write the system prompt

   Write who the agent is, what it must do, and what it must never promise. Keep it concrete. The agent follows it literally.

3. 3

   Pick the AI stack

   The self-hosted stack is Whisper for speech to text, Ollama for the language model and Kokoro for text to speech. Swap in Groq, Gemini or ElevenLabs from the same screen.

4. 4

   Connect a knowledge base

   Upload documents and files, add question and answer pairs, and connect a page by URL. The agent answers from these first and says when it does not know.

5. 5

   Set the voice and language

   Pick a voice and a language for calls. The dashboard is in English, but you can set up an agent in another language — test it thoroughly before you rely on it.

6. 6

   Keep a single prompt, or build a flow

   Only create a conversation flow if you need one — a call that must follow a strict order, such as a compliance script. The flow builder only runs for calls where the agent and all contacts use a published flow.

What voice agent should I start with?

1. 1

   Start with a single prompt

   Describe the whole task in one prompt and let the model run the conversation. A task with several steps still fits in one prompt.

2. 2

   Test it before changing anything

   Try it in the playground and on a real test call. If it works reliably, keep it as a single prompt.

3. 3

   Switch to a conversation flow when you need more control

   Rebuild as a conversation flow if the call must follow a fixed order of steps, like a compliance script.

Templates

The template library has 50 templates in five groups: receptionist (6), support (14), appointment booking (14), outbound (6) and lead qualification (10). The library holds 52 raw entries; 50 appear in the picker - the other two are Build from scratch and Generate from prompt. Pick one, then edit the prompt, knowledge base and voice to match your business.

To see how an agent behaves before you build one, talk to a demo agent from the home page.

Test in text or real audio before an agent ever takes a real call.

1. 1

   Talk to it in the playground

   Open the playground in your dashboard and talk to the agent in text or voice. Read the transcript and check it follows the prompt, uses the knowledge base, and hands off when it should.

2. 2

   Fix the prompt, then test again

   Most bad calls come from a vague prompt. Make the instruction concrete, test again, and only change one thing at a time.

3. 3

   Make a real test call

   Assign a number or a widget to the agent and call it yourself. Then open the call in the dashboard and read the transcript and recording.

Deploy means giving people a way to reach the agent: a phone number, the website widget, or both.

Connect a phone number

1. 1

   Create a Twilio account

   Create a Twilio account at twilio.com and buy a number there, if you do not already have one. Twilio bills you for the calls.

2. 2

   Connect it in the dashboard

   In the dashboard, open Settings → Telephone and connect your Twilio account. Your numbers appear in the dashboard, and your call history and recordings stay in Callingtap.

3. 3

   Assign the number to an agent

   A number can be assigned to any agent. You can only choose between the countries that your carrier account supports.

.

Add the website widget

The website widget puts a voice (and chat) agent on any web page. A widget binds one of your agents to a public key — the key only names the widget, no secrets are exposed, and the server mints short-lived room tokens for each visitor session.

1. 1

   Create a widget

   In your dashboard, open Widgets and create a widget for the agent you want on your site. Copy its public key (it starts withwk_).

2. 2

   Paste the script tag

   Paste one script tag just before the closing</body> tag of your site:

   <script src="https://callingtap.com/widget/embed.js"
                           data-key="wk_your_widget_key"></script>

Adddata-color="#2B4BFF" to tint the launcher button with your brand colour. That is the whole install — the floating button opens a corner panel where visitors talk or chat with your agent, and the conversation lands in your dashboard like any other call.

Go live

Before you tell anyone the number or publish the widget, confirm the agent is assigned, the fallback is set, and a test call sounds right. Then watch the first calls in the dashboard.

Every call leaves a trace in your dashboard. Start there when something goes wrong, or when you want to know how the agent is doing.

1. 1

   Read the calls

   Open the Calls tab and click into a call. It shows the transcript and recording, its duration and its cost.

2. 2

   Watch live calls

   Open Live in the dashboard to see calls as they happen.

3. 3

   Review call quality

   Open Call QA to review calls and recordings after they happen. Use what you find there to fix the prompt, the knowledge base, or the fallback.

4. 4

   Set up alerts

   Open Alerting in the dashboard and turn on notifications, so you hear about failed calls and problems instead of finding them later.

5. 5

   Check reliability

   If calls drop, or the agent behaves badly on real calls, check the reliability settings in the dashboard and the call record first.

Webhooks send the same events to your own systems as they happen. See Webhooks below.

Three ways to run Callingtap. Hosted: we run it, you just use it. Self-hosted: you run it on your server, we license it to you and switch it on.

Hosted plans

1 credit is $0.01 of provider usage. Every minute of calling consumes credits for AI provider usage — the language model, speech to text and text to speech. Your carrier cost is billed separately.

Credits reset every month, and bought top-ups expire after 90 days.

Hosted BYOK — $49 per month

Hosted BYOK is $49 per month. Bring your own keys: connect your Telnyx, Twilio, Plivo or SIP provider accounts and pay carrier rates directly — no per-minute platform fee.

Self-hosted — $1,200 per year, per domain

Self-hosted is $1,200 per year, per domain, on a 12-month licence. The licence is required — it is not free. One licence covers one domain and one installation. A second domain needs a second licence.

Self-hosted licensing — coming, in build

The self-hosted licence server and activation script are being built right now. They are not live yet. The process below is how licensing will work, as planned.

1. 1

   Choose Self-Hosted and pay

   Choose Self-Hosted on the pricing page and pay for a licence. We issue one licence key, bound to your domain, for a set term. Keys look likeCT-SH-XXXX-XXXX-XXXX — that format is an example only. Real keys are generated on our server, never by hand.

2. 2

   We install and activate it

   Our technical team uploads the install file to your server and runs one activation script (working name install-and-activate). The script asks for three things: your domain, your licence key, and the term. The default term is 12 months.

3. 3

   The licence server confirms

   The script contacts the Callingtap licence server with the domain, key and term, and waits for confirmation. The licence server is the source of truth — it stores the domain, term start and expiry, customer name and email, and the status (active, expired or revoked).

4. 4

   The installation unlocks

   On confirmation, the installation unlocks. The script saves the activation on your server, sets the expiry date, and prints a success line with the renewal date. Send that line to the customer.

If activation fails, the script prints the reason in plain words — wrong key, domain mismatch, or licence expired — and nothing is unlocked. Fix the licence record on our side and run the script again. Do not edit the database or config files by hand.

The installation checks in with the licence server in the background. It does not send call recordings, transcripts or customer data — only the licence check.

What the licence includes, and what it does not

Included in the $1,200 per year licence: the full Callingtap software — agents, receptionist, dialer, Call QA, reliability and alerting, as built today — software updates released during the licence term, one activation done by our technical team, email support for licence and activation problems, and re-activation on the same domain if the server is rebuilt.

You pay separately for your server and running costs, your domain name and SSL certificate, your carrier account and call charges, your LLM, speech and voice provider keys and usage, and backups and server maintenance on your side.

Renewal

The term is 12 months from activation, renewable. We email the licence contact 30 days and 7 days before expiry. When you pay, we extend the same key on our server, and the installation picks up the new expiry on its next check-in. No re-install, no new script run.

If you do not renew, there is a 14-day grace period with a visible dashboard warning, then agents stop taking new calls. Calls already in progress are never cut off.

A domain change is allowed once per term, with our approval — we re-issue the key, and the old one stops working. Sharing, reselling or publishing the key ends the licence. There is no one-time or lifetime option: annual only, and no activation fee.

Webhooks let your own system react to call events. Create and manage endpoints in Dashboard → Settings → Webhooks.

1. 1

   Create an endpoint that accepts a POST request

   Your endpoint should respond with any 2xx HTTP status code. It receives the most recent data available at the time your webhook fired, plus a signature.

2. 2

   Set up your endpoint in Callingtap

   Sign in to Callingtap, open Settings → Webhooks, and add your URL. You can also set up a webhook per agent.

3. 3

   Verify the signature

   Every outbound webhook is signed with a random secret calledsigning_secret. We use HMAC-SHA256 to sign the payload, so clients can validate what they receive. Keep your secret private. A leaked secret can be rotated in Settings → Webhooks.

4. 4

   Receive the events

   When an event happens, we send a POST request with the payload to your endpoint.

Events use thecall.completed, call.started, call.failed and appointment.booked formats.

The full API reference for building Callingtap apps is still being written. The REST API is available today at https://api.callingtap.com/api/v1.

1. 1

   Create an API key

   Find your organisation API keys in Dashboard → Settings → API keys.

2. 2

   Call the API with an access token

   List, search and cancel calls and patch appointments — or open a support ticket in the app.

3. 3

   See the call in the dashboard

   Open the Calls tab and click into a call. It shows the transcript and recording, its duration and its cost.

The questions we hear most, answered plainly.

Do I need my own Twilio account?

Yes, to take calls on a phone number you connect a carrier account. Twilio works today. Your carrier bills you for the calls..

What happens when the agent cannot handle a call?

It follows the fallback behaviour in your prompt, such as taking a message, offering a callback, or handing the call to a person. The call is still recorded, with a transcript, so you can see what happened and return it.

Where do my calls and recordings live?

In your dashboard, under Calls. On a self-hosted install, recordings and transcripts stay in your own database and never go to a third-party provider beyond the ones you connected.

Is self-hosted free?

No. Self-hosted is $1,200 per year, per domain, on a 12-month licence. An earlier version of this page said self-hosted services are free — that was wrong.

Does it work in other languages?

The dashboard is in English, but you can set up an agent in another language. Check the language options for that agent, and test it thoroughly before you rely on it.

What does one credit buy?

1 credit is $0.01 of AI provider usage. A minute of calling consumes credits for the language model, speech to text and text to speech. Your carrier cost is separate, unless you are on the BYOK plan and pay providers directly.