Agents

Overview

Agents are AI-powered callers that conduct conversations on your behalf. Each agent has a voice, a language and a duration, and there are two ways to design what it actually says:

Pick a focus and supply questions — a hiring template, described below. This is the original model, which is why an agent is sometimes still called an interview template.
Send a flow and design the conversation yourself — a custom agent. Not hiring-specific, and what to reach for outside recruiting.

Resource Structure

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Technical Screening Agent",
  "instructions": "Evaluates technical skills for software engineering roles",
  "voiceId": "ALEX",
  "type": "ONLINE",
  "focus": "SCREENING",
  "companyPhoneNumberId": "123e4567-e89b-12d3-a456-426614174000", // Required if type is PHONE
  "backgroundSound": "OFFICE", // "OFFICE" or "OFF" — applies to all agent types
  "questions": [
    "Tell me about your experience with React and modern frontend development",
    "Explain how you would design a scalable microservices architecture",
    "Describe a challenging technical problem you solved recently",
  ],
  "duration": 30, // in minutes (max 180)
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
}

Creating Agents

const agent = await fetch("https://api.instaview.sk/agents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INSTAVIEW_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Senior Frontend Developer",
    voiceId: "ALEX",
    type: "ONLINE",
    focus: "SCREENING",
    questions: [
      "Can you describe your experience with React?",
      "How do you optimize for performance?",
    ],
    duration: 30,
  }),
});

Best Practice: For production integrations, always implement request timeouts.

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 10000); // 10s timeout

try {
  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${apiKey}` },
    signal: controller.signal,
  });
} finally {
  clearTimeout(timeoutId);
}

Voice Options

Voice	Gender	Description
`ALEX`	Male	Clear, neutral, business-appropriate (English)
`PETER`	Male	Professional, executive tone (English)
`MIRIAM`	Female	Professional, clear (English)
`SUE`	Female	Warm, approachable tone (localized as Zuzka)
`VIERA`	Female	Clear, articulate (Slovak/Czech optimized)
`CASANDRA`	Female	Professional, clear
`SILVIA`	Female	Clear, neutral
`MICHAEL`	Male	Professional (localized as Michal)
`LUKE`	Male	Young, energetic (localized as Lukáš)
`EMMA`	Female	Warm, friendly (localized as Ema)
`SARAH`	Female	Professional, clear (localized as Sára)
`EVA`	Female	Clear, articulate

Duration: The duration field is specified in minutes. The maximum allowed duration is 180 minutes (3 hours).

Background Sound

backgroundSound controls the ambient noise played to the contact during calls. It can be set on create or updated at any time via PATCH /agents/{id}.

Value	Description
`OFFICE`	Subtle office ambient noise (default)
`OFF`	Complete silence

Speaking for Another Company

An agent introduces itself as the company your API key belongs to. If you call on behalf of your own customers, set overrides on the agent and it speaks as that customer instead:

{
  "overrides": {
    "companyName": "Acme Manufacturing",
    "companyDescription": "Acme makes industrial fasteners and employs 400 people across Slovakia.",
  },
}

Both fields are optional and each falls back to your company profile, so agents without overrides are unchanged. It works on template and custom agents alike.

Send both fields together. They fall back independently, so a companyName on its own leaves your own company’s description in place and the agent introduces itself as Acme while describing you. PATCH also replaces the object whole rather than merging it, so send every field you want kept.

Only what the agent says changes: ownership, billing, analytics and phone-number routing all keep your real company.

Agent Focus Options

focus picks one of four hiring templates, each with its own style of call:

SCREENING
OUTREACH
GENERIC
LANGUAGE_TEST

A first hiring screen - Basic qualifications - Availability - Salary expectations

Custom Agents

The four focus options above are hiring templates: you supply questions, InstaView supplies the rest of the call. A custom agent is the other way round — you design the whole conversation yourself by sending a flow instead of a focus, and the agent runs what you designed. This is what makes an agent usable outside hiring: sales discovery, support callbacks, renewal check-ins, operations checks. Nothing about a custom agent is recruiting-specific. An agent is custom the moment it carries a flow. You never send focus: "CUSTOM" — it is derived, and sending both is rejected.

{
  "name": "Renewal check-in",
  "type": "PHONE",
  "language": "EN",
  "duration": 10,
  "companyPhoneNumberId": "123e4567-e89b-12d3-a456-426614174000",
  "flow": {
    "firstMessage": { "type": "first_message", "text": "Hi {{contact.first_name}}, do you have two minutes?" },
    "sections": [
      { "type": "sequential", "label": "Intro", "prompt": "Say why you are calling." },
      { "type": "looping", "questions": [
        { "question": "How has the setup been working?", "idealAnswer": "No outstanding problems" }
      ]}
    ],
    "lastMessage": { "type": "last_message", "text": "Thanks for your time!" }
  }
}

The four pieces

Field	What it is
`flow`	The conversation itself — a `firstMessage`, one or more `sections`, a `lastMessage`. Sections are `sequential` (a topic, as a free-text prompt), `looping` (questions, each with the answer it is scored against), `conditional` (branches taken on intent) or `human_handoff` (transfer the call to a person, PHONE agents only — the conversation ends there).
`guardrails`	Things the agent must always or never do — “never quote a price”.
`contextConfig`	Who the agent is: `role`, `communicationStyle`, `callToAction`.
`analyticsConfig`	What should come back after the call — see below.

The last three are accepted only alongside a flow; sending them for a template agent is a 422.

You do not describe your company in contextConfig. The description on your company profile is given to every custom agent automatically and resolved at the moment of each call, so editing the profile reaches the next call without touching a single agent.

The first message always discloses the AI

Article 50 of the EU AI Act requires a person to be told they are interacting with an AI system, unless that is already obvious to them, and the duty falls on us as the provider rather than on you. We apply the disclosure unconditionally, without judging whether any given call would qualify as obvious, because that judgement is not one a platform can make per call and the person on the other end is entitled to know either way. So if your flow.firstMessage does not already say so, one short sentence is appended to it at call time, in the agent’s own language. Every language language accepts has its own sentence, so the notice is always in the language the call is held in:

`language`	Appended	`language`	Appended
`SK`	`Som virtuálny hlasový asistent.`	`EL`	`Είμαι ένας φωνητικός βοηθός τεχνητής νοημοσύνης.`
`CS`	`Jsem virtuální hlasový asistent.`	`JA`	`私はAI音声アシスタントです。`
`EN`	`I'm an AI voice assistant.`	`ZH`	`我是人工智能语音助手。`
`DE`	`Ich bin ein KI-Sprachassistent.`	`KO`	`저는 AI 음성 비서입니다.`
`NL`	`Ik ben een AI-spraakassistent.`	`HI`	`मैं एक AI वॉइस असिस्टेंट हूँ।`
`FR`	`Je suis un assistant vocal IA.`	`TA`	`நான் ஒரு AI குரல் உதவியாளர்.`
`ES`	`Soy un asistente de voz con IA.`	`AR`	`أنا مساعد صوتي يعمل بالذكاء الاصطناعي.`
`IT`	`Sono un assistente vocale IA.`	`RU`	`Я голосовой помощник с искусственным интеллектом.`
`PT`	`Sou um assistente de voz com IA.`	`UK`	`Я голосовий помічник зі штучним інтелектом.`
`PL`	`Jestem asystentem głosowym AI.`	`BG`	`Аз съм гласов асистент с изкуствен интелект.`
`HU`	`AI hangasszisztens vagyok.`	`ID`	`Saya adalah asisten suara AI.`
`RO`	`Sunt un asistent vocal AI.`	`MS`	`Saya ialah pembantu suara AI.`
`HR`	`Ja sam AI glasovni asistent.`	`FIL`	`Ako ay isang AI voice assistant.`
`SV`	`Jag är en AI-röstassistent.`	`VI`	`Tôi là trợ lý giọng nói AI.`
`DA`	`Jeg er en AI-stemmeassistent.`	`FI`	`Olen tekoälyn puheavustaja.`
`NO`	`Jeg er en AI-stemmeassistent.`	`TR`	`Ben bir yapay zekâ sesli asistanıyım.`

// Sent:
{ "firstMessage": { "type": "first_message", "text": "Dobrý deň, tu je Jana zo spoločnosti Acme." } }

// Spoken:
// "Dobrý deň, tu je Jana zo spoločnosti Acme. Som virtuálny hlasový asistent."

Nothing is appended when your opening already discloses. We look for the artificial part, not the assistant part, in every language in the table: virtuálny / virtuální, umelá inteligencia / umělá inteligence, automatizovaný, hlasový asistent, a standalone AI, artificial intelligence, virtual assistant, automated, künstliche Intelligenz, sztuczna inteligencja, kecerdasan buatan, 人工知能, and similar. A bare “assistant” or “asistent” does not count, because a company assistant who is a human being is an ordinary thing to be. Nor does AI sitting inside a company name: an opening that says “calling from AI Talent Partners” and nothing else has not disclosed, and will still get the sentence. Your stored firstMessage is never rewritten: the sentence is added on the way to the call, and reading the agent back returns exactly what you sent. To control the wording yourself, write your own disclosure into firstMessage and ours will not be added.

Getting structured data back

Without analyticsConfig, a custom agent places a call and returns a transcript. With it, you get data your own systems can act on — the difference between “here is what was said” and “budget confirmed: true, meeting booked: yes”.

"analyticsConfig": {
  "extractionTargets": [
    { "key": "budget_confirmed", "label": "Budget confirmed", "type": "bool",
      "ideal": "A confirmed budget of at least 10k", "importance": "REQUIRED", "weight": 50 }
  ],
  "scoringCriteria": [{ "label": "Handled objections", "description": "…", "weight": 20 }],
  "outcomes": [{ "label": "Meeting booked", "description": "Agreed a specific day" }],
  "outputTags": [{ "label": "Needs follow-up", "description": "Asked to be called back" }]
}

extractionTargets — values pulled out of every call. One with an ideal also counts toward the match score.
scoringCriteria — holistic judgements over the whole call.
outcomes — did the call achieve what it was for? Decided met / not met.
outputTags — labels the AI may apply.
capture — which qualitative artefacts to produce (summary, Q&A, evaluation, sentiment, recording, transcript). All default to true.

Every item has a key, and it is yours: it is the field name the results come back under, so your code switches on it. Omit it and InstaView derives a slug of the label — convenient, but renaming the label later silently moves the results to a new key. Set it when your integration reads results by name. Results arrive as analytics on the conversation and on the analysis.completed webhook. See Conversations.

Scoring a flow question is set inline on the question, not in analyticsConfig — add importance and weight to the question itself. Questions are addressed by ids InstaView mints, which you cannot know while writing the flow. A question with an idealAnswer but no importance or weight is asked but not scored, and idealAnswer itself is optional — omit it for a question that has no right answer.

Personalising each call

Any text in a flow may contain {{contact.<key>}} placeholders. They are resolved per call, not when the agent is created, so one agent serves everyone you call. first_name, last_name, email, phone, company_name, company_description and agent_name are always available; add your own by sending them as the contact’s fields.

Custom agent reference

Full flow schema, validation errors, key rules and analytics configuration

Knowledge Base

Any agent — template or custom — can be given documents to consult mid-call: a job spec, a benefits summary, a pricing sheet, an FAQ. The agent looks them up on its own when the conversation calls for it; you do not have to reference them anywhere in the flow. Attaching one is a three-step flow, because the file goes straight to storage rather than through this API:

# 1. Reserve a slot and get an upload URL
curl -X POST https://api.instaview.sk/agents/$AGENT_ID/knowledge \
  -H "Authorization: Bearer $INSTAVIEW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "fileName": "benefits.pdf", "mimeType": "application/pdf", "sizeBytes": 482133 }'

# 2. PUT the bytes to the returned uploadUrl — no API key on this request
curl -X PUT "$UPLOAD_URL" -H "Content-Type: application/pdf" --data-binary @benefits.pdf

# 3. Confirm, which verifies the stored file and makes the document usable
curl -X POST https://api.instaview.sk/agents/$AGENT_ID/knowledge/$DOCUMENT_ID/complete \
  -H "Authorization: Bearer $INSTAVIEW_API_KEY"

PDF, DOC/DOCX, TXT, MD, CSV, TSV, JSON, XML and YAML are accepted, up to 20 MB and 10 documents per agent. Documents can be deactivated to park them without losing them, and deleting one erases the file for good.

Uploads are rate limited more tightly than the rest of the API. Reserve slots as you need them rather than in a burst — see the endpoint reference for the current numbers.

Knowledge base reference

The full upload flow, limits, verification rules and error cases

Best Practices

Clear Questions

Write specific, open-ended questions

Appropriate Duration

15-30 minutes for most calls

Test First

Test agents before using in production

Iterate

Refine based on how the calls go

Next Steps

Conversations

See how a conversation uses an agent

API Reference

View complete Agents API reference

Getting Started

Core Concepts

Resources

Advanced

Overview

Resource Structure

Creating Agents

Voice Options

Background Sound

Speaking for Another Company

Agent Focus Options

Custom Agents

The four pieces

The first message always discloses the AI

Getting structured data back

Personalising each call

Custom agent reference

Knowledge Base

Knowledge base reference

Best Practices

Clear Questions

Appropriate Duration

Test First

Iterate

Next Steps

Conversations

API Reference

​Overview

​Resource Structure

​Creating Agents

​Voice Options

​Background Sound

​Speaking for Another Company

​Agent Focus Options

​Custom Agents

​The four pieces

​The first message always discloses the AI

​Getting structured data back

​Personalising each call

Custom agent reference

​Knowledge Base

Knowledge base reference

​Best Practices

Clear Questions

Appropriate Duration

Test First

Iterate

​Next Steps

Conversations

API Reference

Overview

Resource Structure

Creating Agents

Voice Options

Background Sound

Speaking for Another Company

Agent Focus Options

Custom Agents

The four pieces

The first message always discloses the AI

Getting structured data back

Personalising each call

Knowledge Base

Best Practices

Next Steps