Build AI agents that call, chat and follow up with your customers

Core concepts

A handful of objects make up everything you do on the platform.

How a voice call flows

1. Dial or answerA campaign, the API, or an inbound call to one of your numbers starts the call over your SIP trunk.
2. GreetThe agent speaks its Opening Message in the agent's primary language, or lets the language model open the call from the System Prompt.
3. ConverseSpeech to text transcribes the caller, the language model decides what to say or which tool to call, and text to speech speaks the reply. The caller can interrupt at any time.
4. Hand off or endThe agent can transfer to a work queue, or end the call when the conversation is finished.
5. After the callThe platform stores the recording and transcript, extracts your structured fields, scores quality, and sends conversation.ended to your webhooks.

Get started

Quickstart: your first voice agent

You need an account with the agents.edit permission. To call real phones you also need a voice channel with at least one number; your admin may have set one up already.

1. Create the agentGo to Build → AI agents, click + New and choose Voice Agent.
2. Describe the jobOn the Prompt tab, write what the agent should do in plain words, for example: “Remind customers that their EMI of {{amount}} is due on {{due_date}} and ask when they will pay.” Add amount and due_date under Variables, then generate. The platform writes the Description, Opening Message and System Prompt for you.
3. Check identityOn Identity, set the agent and persona name and review the Opening Message and AI Disclosure.
4. Pick a voice and languageOn Voice & AI models, select the languages the agent speaks, set the primary language, then pick a voice. Leave the speech to text and language model pickers blank to use the platform defaults.
5. Save and testSave the draft, open the test console, enter your own phone number and values for the variables, and place a test call. Or use Playground to talk in the browser.
6. PublishWhen the agent sounds right, publish it with a short release note. Only published versions run in campaigns and inbound calls.

Next steps: attach an inbound number, launch a campaign, or place calls from your own system.

Finding your way around

The sidebar groups pages by what you are doing. What you see depends on your role and on features enabled for your organization.

Build agents

Agent types

Click + New in Build → AI agents to pick a type.

A voice agent's settings are split into sections, in this order: Prompt, Identity, Voice & AI models, Knowledge, Skills, Tools, Transfer, Telephony, Ambience & silence, Quality. Everything after Voice & AI models unlocks once the agent has a System Prompt. Website agents show only the sections that apply to chat.

Prompt & variables

User Prompt

Write the prompt in your own words. It is an instruction to the agent, not a script to read out. Say who the agent is calling, what it must achieve, what it must never do, and when the call is finished.

Variables

Variables personalize each call. Add a name (for example deliveryDate) and an optional description or example, then use it in the prompt as {{deliveryDate}}. Values come from contact fields in a campaign, from the variables object in the API, or from tool responses during the call.

Prompt Verifier and generation

The Prompt Verifier checks that your prompt states a Purpose and a Goal. It is advisory and never blocks generation. Generating fills the Description, Opening Message and System Prompt.

Writing prompts that work on the phone

• Ask one question per turn. Long monologues get interrupted and confuse callers.
• Write amounts and dates the way they should be spoken.
• Only mention tools and transfers the agent actually has. If the prompt promises a transfer the agent cannot perform, it will improvise.
• State clearly when to end the call, for example after confirming a payment date or when the caller asks to stop.

Identity & opening message

The opening message is spoken in the agent's primary language. Write it in that language.

Voice & AI models

Each voice agent runs three models: speech to text (STT) hears the caller, a language model (LLM) decides the reply, and text to speech (TTS) speaks it. Pin a provider and model for this agent, or leave the picker blank to use the platform default.

Which of these you can pick depends on the provider keys your organization has configured. If a picker is empty, ask an admin to add the provider's API key.

Choosing a voice

• Filter by provider and model. Voices are sorted by recommendation by default.
• The list only shows voices that can speak every language you selected. Adding one more language can hide a whole provider.
• Speaking speed: 0.7 to 1.2 in steps of 0.1. Default 1.0.

Languages

Select at least one language. Supported languages: English (India), Hindi, Tamil, Telugu, Marathi, Bengali, Kannada and Gujarati.

• Primary language (required): the agent greets in this language.
• Auto language negotiation (shown when you pick more than one language): if the caller replies in another supported language, the agent asks once whether to switch, then keeps that language for the rest of the call.

For Hinglish callers, choose Hindi as the primary language and say in the prompt that the agent should speak conversational Hindi with common English words.

Knowledge base

A knowledge base gives the agent facts it can search during a call, such as product details, policies and FAQs.

1. CreateIn Build → Knowledge base, give it a Name and a Description. The description is required: the agent reads it to decide when to search.
2. Add sourcesUpload files, add a URL, or paste text. Files: PDF, DOCX, TXT, CSV, MD, JSON, up to 10 MB each and 50 documents per knowledge base.
3. Wait for indexingEach document moves from Processing to Indexed. A Failed document can be removed and uploaded again.
4. TestType a question in the test query box and check the passages that come back.
5. AttachClick “Attach to agents”, or open an agent's Knowledge section.

On the agent you can tune two settings: Relevance threshold (0.4 to 0.95, higher returns fewer, closer matches) and Result count (1 to 10 passages per search).

Skills

A skill is a reusable, versioned block of behavior you can pin to many agents, such as “handle a payment dispute” or “verify identity”.

Use Generate with AI to draft the fields, check the prompt preview, and publish. Every publish creates an immutable version, and the version history and audit log show who changed what.

Tools (function calling)

Tools let the agent call your APIs: look up a balance, book a slot, create a ticket. Create the tool once in Build → Tools, then bind it to agents.

Tool definition

Binding a tool to an agent

• Trigger: In-call (the LLM decides when to call it) or Pre-call (runs before the call starts, e.g. to fetch customer data). Pre-call tools cannot use LLM-filled parameters.
• Parameter sources: Contact field, System value, Agent variable, Call variable, or Dynamic (the LLM extracts it from the conversation).
• Optionally override the description the LLM sees for this agent, and run a binding test.

Platform tools such as WhatsApp messaging and web search are available without any setup.

Transfers & work queues

Work queues

Create queues in Build → Work Queues.

Transfer rules on the agent

• Conditional transfer rules are checked top to bottom. Each rule has conditions (field, operator > < = >= <= !=, value) joined with and/or, and a target work queue. Turn on AI summary so the human sees a recap before picking up.
• Default handoff policy decides what happens when no rule matches.

Agent telephony settings

Ambience & silence

• Background ambience (off by default): Office, City, Forest or Crowded room, with volume.
• Thinking sound: keyboard typing while the agent looks something up, with volume.
• Emotional delivery (off by default): expressive speech. How much applies depends on the voice.
• Silence watchdog (off by default): if the caller is silent for the threshold (3 to 60 seconds), the agent checks in; after the maximum tries (1 to 5) it hangs up. Works for English, Hindi and Marathi.

If callers report hearing chatter or typing they did not expect, check these settings first.

Post-call extraction

After each call the platform reads the transcript and fills structured fields you define, such as promise_to_pay_date or interested. Results appear in the conversation, in dashboards, in the conversation.ended webhook and through the API.

Each field has a name, a description, a type, a Required flag and, for lists, the allowed values.

Add extraction instructions for rules the model should follow, for example “Dates are in DD/MM/YYYY”. An estimated cost per call is shown as you add fields. You can re-run extraction on a past call from the API.

Testing & publishing

Test console

Enter a country and phone number, fill in call variables, and save them as a preset for next time. You can also test WhatsApp Calling. Test calls always use the last saved draft.

Playground

Build → Playground runs the agent in your browser and shows the call and system variables in use.

Quality settings

• Choose a QA profile, a sampling rate (10% to all calls) and a minimum call duration to score.
• Target extra sampling at high-risk calls, escalated or transferred calls, and calls on a new agent version.

Publishing

The publish readiness panel checks that the voice speaks every language, that the agent passed a regression test, and that it has human approval. Add a release note and publish. Earlier versions stay in the version list.

Other channels

IVR flows

An IVR flow is a menu built from steps: Start, Speak, Listen, Transfer, End. Listen steps accept keypad (DTMF), speech, or both. Transfer steps can route to a voice agent, a queue, a phone number or a webhook. Handle the No Response, Invalid Input and Max Retries events so callers are never stuck.

Website chat widget

1. Create a deploymentIn Build → Deployment, give it a name, choose the agent and environment.
2. Design the widgetBrand colour, theme (Light, Dark, Auto), launcher (Bubble or Bar), position, font, corner radius, header title, bot name and greeting. Set business hours, an away message and a closing message.
3. Allow your domainsAdd every domain the widget will run on. With no allowed domain, every request is refused.
4. InstallCopy the snippet from Install & domains into your site, or use the Google Tag Manager or WordPress instructions. See Web SDK.
5. PublishTrack chats started, containment, handover rate, first response time and satisfaction on the deployment page.

If the site key leaks, rotate it from the install tab and update your snippet.

WhatsApp

1. ConnectAdd a WhatsApp channel through Facebook embedded sign-up. Your number can keep working in the WhatsApp Business App.
2. Choose who answersUnder AI Answering, pick an AI agent or a WhatsApp bot, optionally pinned to a version.
3. TemplatesMessages that start a conversation must use a Meta-approved template. Templates show as Approved or Pending.
4. MonitorRead conversations under Threads, configure human handover, and try the agent in Test Agent.

SMS & email agents

SMS agents need a DLT header and DLT template ID. You can set a send window, a frequency cap, messages per second and holidays.

Email agents send through your own domain. Configure the email channel with a sender name, sending domain and SMTP details (host, port, TLS or STARTTLS, username, password).

Journeys

A journey chains agents across channels, for example a QR scan that opens WhatsApp, then a voice call if there is no reply, then an email with a booking link.

Steps: QR entry, WhatsApp agent, Voice agent, Email agent, Condition, Update context, End. Each step has a stage instruction, the agent to use, maximum attempts and a reply timeout. Conditions branch on what earlier steps extracted. Track each customer's progress under Sessions.

Telephony

Channels

Channels live in Build → Channels. Types: Voice, WhatsApp, SMS, Email, RCS and Website. A voice channel bundles a SIP trunk, its phone numbers, a default language, a time zone and the call direction (inbound, outbound or both).

Connect a SIP trunk

Convophi calls over your own carrier. Supported providers: Vobiz, Exotel, Twilio Programmable Voice, Plivo, Telnyx, LiveKit Cloud SIP, WhatsApp Business Calling, and any other SIP provider.

1. DetailsChannel name, description, channel language, time zone and tags.
2. SIP configurationSIP provider, username, password, SIP address or proxy, and maximum concurrent calls (0 means unlimited).
3. Phone numbersAdd numbers in E.164 format, e.g. +918065355253. Numbers can only be added after the SIP settings are saved.
4. Call directionInbound, outbound or both.
5. Review & provisionThe platform creates inbound and outbound trunks. Each shows Pending until it is Ready; retry from the channel panel if one stays pending.

Phone numbers & inbound calls

Phone numbers are managed inside their channel. To answer inbound calls, open the agent's Telephony section and add the number under Inbound numbers. Each number can belong to one agent, and the change takes effect immediately.

An inbound call is refused when the agent is unpublished, when the agent or channel is at its concurrency limit, or when the wallet has no balance.

Operate

Contacts & lists

• Lists (segments) group contacts; give each a name and colour.
• Import an Excel (.xlsx, .xls) or CSV file with up to 100,000 rows, or paste CSV/TSV. Download the template, map columns, and set country rules for phone numbers. Mapping an External ID is recommended so re-imports update instead of duplicating.
• DND/NCPR and consent scrubbing runs automatically on import.
• API / CBS sync pulls contacts from your system on a schedule: endpoint URL, method, auth (e.g. an X-Api-Key header), records path and sync interval.
• Open a contact to see their 360 profile and history, or call them directly.

Campaigns (batch calling)

1. Channel & audiencePick the voice channel, name the campaign, and choose a contact list with optional filters.
2. Agent & scriptPick a published agent and map contact fields to agent variables. Choose “Skip” for variables you do not want to personalize. Optionally set up an A/B test between agents.
3. ScheduleRun manually or on a schedule, with a calling window, days of the week and a time zone.
4. Review and launchEach launch creates a run.

Launch settings

Contacts in the list are captured when the run starts. Contacts added later join the next run.

Statuses

You can pause, resume or stop a run at any time and download its report.

Agent Desktop

Agent Desktop is where human agents pick up transferred calls and work items. During a call you can leave (the AI takes over again) or end the call for everyone. Afterwards, record a disposition such as Promise-to-pay (with amount in ₹), Partial paid, Callback, Refused to pay, Dispute raised, Wrong number, No answer or Do-not-contact, and add notes and tags.

Monitor

Conversations & recordings

Monitor → Conversations lists every call and chat.

• Filters: source (Voice, WhatsApp, SMS, Email, RCS, Website), direction, status, flags (Flagged, High latency, Too short), date range, agent, campaign and outcome.
• Summary: total calls, connect rate, average QA score, average sentiment and flagged calls. Export the filtered list.
• Detail: transcript, insights, recording and timeline, plus tool calls, extracted fields and QA status. Add notes and tags, flag a call, share or download it.

Use Start new conversation to call a single contact or number with a chosen agent.

Call statuses

Live & analytics

A real-time wall showing calls in progress, queue depth, longest wait, occupancy, abandons, connect rate, callbacks today and SLA. It refreshes every 3, 5 or 10 seconds.

Dashboards

Build dashboards from a blank canvas or a template (Operations Overview, Campaign Dashboard, Loan Recovery Agent, Agent Intelligence). Widgets include KPIs, charts, tables, Markdown text and embeds, and can chart your extracted fields.

Handoff & transfer

Shows active escalations, direct transfers, queue destinations and warm handoff rate, with each transfer's destination type (AI agent, human agent, queue or supervisor) and mode.

Quality

QA scoring

A scoring profile defines how calls are graded. It combines rubric criteria (grouped in weighted categories), auto-fail gates, system KPIs such as latency, and custom KPIs. Attach a profile to an agent and choose a sampling rate in the agent's Quality section. Scores appear on each conversation and in Quality Monitor.

Simulation Studio

Simulations have an AI caller talk to your agent so you can test before real customers do.

1. Describe what to testPick scenarios from the library, a dataset, a free prompt, or generate them with AI.
2. Mix it upSet the difficulty mix (easy, medium, adversarial), caller personas (neutral, frustrated, angry) and language mix.
3. LaunchChoose simulations per scenario, concurrency (1, 3, 5 or 10), a QA rubric, and whether to score automatically.
4. ReviewOpen the run report to read each simulated call, its score and its failures.

Save passing sets as regression suites and re-run them before each publish. The Prompt Rewriter suggests prompt changes based on failures.

Audio Analysis

Score recordings from outside the platform, such as calls from your human call centre. Upload up to 20 files per batch (.mp3, .wav, .m4a, .ogg, .flac) and pick a scoring profile. The platform transcribes, separates speakers and scores each call.

To send files automatically, use the API:

curl -X POST https://api.voice.variphi.com/api/v1/audio-analysis/batches \
  -H "Authorization: Bearer $VARIPHI_API_KEY" \
  -F "name=September QA sample" \
  -F "profile_id=<scoring-profile-id>" \
  -F "files=@call.mp3"

Quality & audit

Human reviewers check AI-scored calls in a review queue. The page tracks agreement between the AI judge and reviewers, scoring bias, and disputed reviews. Scores fall into five tiers: Poor, Fair, Good, Very good and Excellent.

Account

Users & roles

Invite users from Govern → Users & roles. Invitees accept by email and set a password.

Create custom roles from a base role and adjust permissions such as agents.publish, campaigns.manage, contacts.export or calls.listen. Roles are granted per workspace, so check that a user has the role in the workspace they are working in.

Settings & compliance

Billing & credits

Calls are paid from a prepaid credit balance. Billing & usage shows your plan, balance and a ledger of every charge and top-up. Click Add credits to pay in ₹ through Razorpay.

API reference

Overview & authentication

The Partner API lets your systems create agents, place calls, run campaigns, sync contacts and read results.

Get an API key

Go to Govern → Partner API and create a key. Live keys start with vp_live_, test keys with vp_test_. The secret is shown once; store it in your secret manager. You can rotate or revoke keys from the same page.

Send the key in the X-Api-Key header (or as Authorization: Bearer vp_live_…). Every example on this page reads it from the VARIPHI_API_KEY environment variable. Pick your language once and every example switches with it.

Server-to-server integrations can instead use OAuth client credentials and send the access token as Authorization: Bearer <token>. Ask your account team for a client.

Conventions

• Every response uses the envelope {"data": …, "meta": {"request_id", "page", "page_size", "total"}, "error": …}.
• Send an Idempotency-Key header on POST requests so retries never place the same call twice.
• Pass X-Request-Id to trace a request; it is echoed back. Responses carry X-API-Version: v1.
• Phone numbers are always E.164, e.g. +919876543210.

Agents

Only display_name is required.

Calls

A call is a conversation. Create one to dial a number.

agent_id and phone_number are required. contact_id and channel_id are optional. Variable values are strings.

Read the transcript

Rather than polling, subscribe to conversation.ended.

Campaigns

A campaign definition is the reusable setup. Launching it creates a campaign run.

Contacts

Webhooks

Webhooks push events to your HTTPS endpoint. Add endpoints in Govern → Partner API or through the API. You can filter by field, for example only calls from one agent, and send a test event.

Events

Subscribe to a whole family with a wildcard: conversation.*, campaign.*, contact.*, quality.*.

Up to 10 filters, each with up to 50 values. Operators: eq, neq, in, not_in. The signing secret is shown once when you create the endpoint; rotate it with POST /webhook-endpoints/{id}/rotate-secret.

Payload

{
  "id": "evt_…",
  "type": "conversation.ended",
  "created_at": "2026-09-25T11:42:07Z",
  "api_version": "v1",
  "data": {
    "agent": { "id": "agt_…" },
    "conversation": { "id": "conv_…", "status": "completed", "outcome": "…" },
    "call": { "id": "…", "phone_number": "+919876543210" },
    "campaign": { "id": "…", "status": "…" },
    "contact": { "id": "…", "name": "Ravi Kumar", "primary_phone": "+919876543210" }
  }
}

Verify the signature

Each delivery carries X-Webhook-Id, X-Webhook-Delivery-Id, X-Webhook-Timestamp (Unix seconds) and X-Webhook-Signature. The signature is sha256= followed by the hex HMAC-SHA256 of {timestamp}.{raw body} with your signing secret. Reject requests older than 5 minutes.

const crypto = require("crypto");

app.post("/hooks/variphi", express.raw({ type: "application/json" }), (req, res) => {
  const ts = req.header("X-Webhook-Timestamp");
  const sig = req.header("X-Webhook-Signature") || "";
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(400);

  const expected = "sha256=" + crypto
    .createHmac("sha256", process.env.VARIPHI_WEBHOOK_SECRET)
    .update(`${ts}.${req.body}`)
    .digest("hex");
  if (sig.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.sendStatus(401);
  }

  const event = JSON.parse(req.body);
  // dedupe on event.id, then process
  res.sendStatus(200);
});

import hmac, hashlib, time

def verify(secret: str, ts: str, raw_body: bytes, signature: str) -> bool:
    if abs(time.time() - int(ts)) > 300:
        return False
    mac = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256)
    return hmac.compare_digest("sha256=" + mac.hexdigest(), signature)

Retries

Return any 2xx within 10 seconds. On a 5xx, 408, 429 or network error the platform retries up to 10 times, backing off from 30 seconds to 12 hours. The same event can arrive more than once, so deduplicate on id. Inspect attempts under Recent Deliveries or GET /webhook-endpoints/{id}/deliveries.

Other endpoints

List recent calls

The full list, with request and response schemas, is in /openapi.json. A Postman collection is available from your account team.

Web SDK

Add the chat widget to any site with one script tag. Get your site key from the deployment's Install & domains tab.

<script async src="https://d3q3xlmdjsdb78.cloudfront.net/widget.js"
        data-site-key="vf_live_…"></script>
<script>
  window.Convophi = window.Convophi || function () {
    (window.Convophi.q = window.Convophi.q || []).push(arguments);
  };
  // Optional: tell the agent who the visitor is
  Convophi("identify", { email: "visitor@example.com", name: "Visitor" });
</script>

Commands: identify, open, close, end, destroy.

React

npm install @convophi/ai-web-chat-react

import { WebAgentProvider, useConversation } from "@convophi/ai-web-chat-react";

function Chat() {
  const { messages, sendMessage, isStreaming } = useConversation();
  // render messages, call sendMessage(text)
}

export default function App() {
  return (
    <WebAgentProvider siteKey="vf_live_…">
      <Chat />
    </WebAgentProvider>
  );
}

Help

Troubleshooting & FAQ

Glossary

Convophi platform documentation · Updated 25 September 2026