Skip to content
Mahvash/API documentation
فارسی

Guides

Voice support desk

Turn a recorded support call into a transcript, a knowledge-backed draft reply, and optionally spoken audio — with a human deciding what is sent.

How the pieces connect

  1. 01Call recording
  2. 02Support backend
  3. 03Transcribe → respond → speak
  4. 04Agent workspace

A real-world example

Take Sepehr Net, an internet provider with a busy call center. After every call, an agent has to write a summary, decide what to do next and often send the customer a follow-up. That note-taking takes time and the quality varies from agent to agent.

With Mahvash, each recorded call is transcribed automatically, a follow-up message is drafted from the company's troubleshooting guide, and — once an agent approves it — the message can also be turned into a short audio clip for the callback system.

What the team gets

  • No manual note-taking. Every call has a searchable transcript attached to the ticket.
  • Better follow-ups. Drafts use the official troubleshooting steps, not memory.
  • Flexible delivery. The same approved text can be sent as a message or played as audio.
  • Human approval built in. Nothing is sent or spoken to a customer without an agent's decision.

See it with a real call

StepWhat happensIn this example
1. Call recordedThe phone system saves the recording and creates a ticket.A three-minute call about slow internet, call-58213.m4a.
2. TranscriptMahvash turns the audio into text.“My internet has been very slow every evening this week, especially after eight…”
3. Follow-up draftA reply is drafted from the troubleshooting guide.“Evening slowdowns are often caused by Wi-Fi congestion. Please try a cable connection…”
4. Agent approvalThe agent adds a line-test offer and approves.Approved text saved on the ticket.
5. Audio (optional)The approved text becomes a short audio message.followup-58213.mp3 for the callback system.

The three API calls behind those steps:

curl https://api.mahvashai.ir/v1/audio/transcriptions \
  -H "Authorization: Bearer $MAHVASH_PROJECT_KEY" \
  -F model="$TRANSCRIPTION_MODEL" \
  -F file=@call-58213.m4a

# Response
{ "text": "Hi, my internet has been very slow every evening this week, especially after eight. During the day it is fine. I already restarted the modem twice." }

Each step is a separate call, so the application can stop after the transcript, ask for approval before generating speech, and retry one step without repeating the others.

Note:The company, customer and policy details in this example are fictional. Mahvash answers from the documents and data you provide; it does not invent your policies.

The call stays in your workflow

Your telephony or help-desk service records calls under its own consent and retention rules. Its backend sends the recording to Mahvash for transcription, then passes the text through the same project-scoped response flow as a written ticket.

Mahvash does not place calls or talk to your customer. It returns text and audio; your system decides what to do with them.

Choose audio-capable models

  • Discover a transcription model and, if you want spoken replies, a speech model and voice, using GET /v1/models.
  • Keep the project key server-side.
  • Add a vector store with your support policies if replies must cite them.

API actions in this step

GET List enabled logical AI models ↗

Transcribe, answer, speak

  1. 1Send the recording as multipart data to /v1/audio/transcriptions and save the transcript.
  2. 2Let an agent review the transcript, or route it automatically.
  3. 3Send the transcript text to /v1/responses, optionally with file_search.
  4. 4If an approved reply should be spoken, send it to /v1/audio/speech, which returns binary audio.

API actions in this step

POST Transcribe an uploaded recording ↗POST Create a response ↗POST Synthesize speech and return the audio bytes ↗

Backend pipeline

The example keeps the three calls separate, so your application can stop after transcription, or require a human approval before generating speech. Save the transcript and the response ID with the ticket, and store generated audio under your own access policy.

Implementation example

const api = "https://api.mahvashai.ir";
const auth = { Authorization: "Bearer " + process.env.MAHVASH_PROJECT_KEY! };
const form = new FormData();
form.set("model", process.env.TRANSCRIPTION_MODEL!);
form.set("file", callRecording); // File or Blob supplied by your app
const transcript = await fetch(api + "/v1/audio/transcriptions", {
  method: "POST", headers: auth, body: form
}).then(r => r.json());
const reply = await fetch(api + "/v1/responses", {
  method: "POST", headers: { ...auth, "Content-Type": "application/json" },
  body: JSON.stringify({ model: "auto", input: "Draft an agent response to: " + transcript.text })
}).then(r => r.json());
await db.calls.saveSuggestion(callId, { transcript: transcript.text, responseId: reply.id });
// After agent approval, use the approved text for speech.
const audio = await fetch(api + "/v1/audio/speech", {
  method: "POST", headers: { ...auth, "Content-Type": "application/json" },
  body: JSON.stringify({ model: process.env.SPEECH_MODEL, voice: process.env.SPEECH_VOICE, input: approvedText })
});
await storage.save(callId, await audio.arrayBuffer());

Example response checkpoint

{
  "text": "I need help resetting my account password."
}

Illustrative response excerpt. Your application owns the surrounding workflow and customer data.

Agent workspace output

Present the transcript, the suggested reply with its citations, and an optional playable audio file. Label which steps are still pending so an agent never mistakes a generated draft for a reply that was already sent.

Partial success

Each stage can succeed or fail on its own. Transcription can succeed while generation or speech fails.

  • Keep the successful transcript and every X-Request-ID.
  • Show which stage failed and let the agent continue manually.
  • Do not repeat a paid generation whose outcome is unclear; retrieve it by response ID first.

Use the same pattern for

  • Clinics and booking lines — call summaries and appointment follow-ups, with the caller's consent.
  • Delivery and logistics — turning driver or customer calls into structured tickets.
  • Utilities — outage and billing calls summarized for the next shift.
  • Sales teams — call notes and follow-up emails drafted for review.
← All integration scenarios