Appearance
Bot designer and Voice and calls
This page documents two AI Studio screens: the Bot designer, which builds business bots on top of the agent engine, and Voice and calls, which holds phone lines, calls, campaigns and the voice settings of agents. A bot and a voice agent are one agent with extra settings; chat, WhatsApp, the website and the phone are its channels. For the task-oriented overview see Build a bot; for the agent itself see Build an agent.
Bot designer
Where to find it
Workspace > AI Studio > Bot designer. Page key ai-bots.
Bot list
The top row counts Bots, Published, With triggers, With voice and On portals. Each card shows the bot name, type, status, its business need (No business need written yet. when empty) and chips for voice and portal members. New bot opens the creator.
New bot
Two ways to start:
- Describe the business need. Enter at least 10 characters (
Describe the business need in a sentence or two.), optionally choose a Type (or let AI choose), and select Draft the bot. The draft uses only your own entities, tools and knowledge bases. Nothing is created until you save it. - Start from a template. Use this template opens the editor with the template's type, need, instructions, starter questions and flow filled in. Templates leave tools, e-mail addresses and trigger entities empty on purpose, because they travel between organisations; the designer flags each empty step. A template that expects data shows an info message naming it ("This template expects data such as ...").
Bot types
| Type | Used for |
|---|---|
| Assistant | Answers people's questions from data and knowledge. |
| Transaction | Creates or changes records for people, for example leave, orders, expenses. |
| Workflow | Starts and moves workflows, approvals and tasks. |
| Monitoring | Watches records and thresholds and reacts. |
| Knowledge | Answers from documents and policies. |
| Analytics | Reads figures and explains them. |
| Automation | Runs on a schedule or an event, with no one asking. |
| Autonomous | Plans several steps toward a goal, within approvals. |
Bot editor, Design tab
The editor has four tabs: Design, Triggers, Voice, Test. The last three are enabled after the first save.
| Field | Description |
|---|---|
| Name | Required. |
| Code | 2 to 60 lower-case letters, digits and dashes; fixed after the first save. Otherwise: The code is 2 to 60 lower-case letters, digits and dashes. |
| Type | One of the types above. |
| Business need | Up to 2,000 characters. |
| Instructions | Required (Write the bot's instructions.). Written to the bot in the second person. The flow below is added to them as the bot's procedure. |
| Business data | Entities the bot reads or changes. For each entity choose the operations find, get, create, update. Record tools named entity.<entity>.<operation> are generated when you save, and they run as the person, so the entity's own access rules apply. The entity name must be letters, digits and _ . -, starting with a letter. |
| Starter questions | Suggested first questions, entered one at a time. |
| Answer signed-in portal members about their own records | Turns on portal member tools. Portal code, the portal's entities the member's records come from, and Portal search. Choose search or at least one entity: For portal members, choose the portal's search or at least one of its entities. |
The bot is created as a draft. Publish it in the Agent designer after adding triggers and voice and testing it.
Flow steps
The flow is an ordered list of steps that becomes the bot's written procedure. Steps can be moved up and down.
| Step | Reference | Required reference | What it means |
|---|---|---|---|
| Trigger | none | no | What starts the bot. The real trigger is set on the Triggers tab. |
| Read data | Tool | no | Reads records through a tool, as the person. |
| Search knowledge | Knowledge base | no | Searches documents and policies. |
| Reason | none | no | Thinks about what it found. |
| Condition | none | no | Only goes on when this holds. |
| Action | Tool | yes | Creates or changes a record through a tool. |
| Start workflow | Tool | yes | Starts a workflow through a workflow tool. |
| Call an API | Tool | yes | Calls an outside system through a tool. |
| Approval | none | no | The next action waits for a person's approval, whatever its risk. |
| Hand to a person | Team | no | Hands the conversation to a team. |
| Notify | E-mail addresses | yes | E-mails only the addresses listed (up to 10). |
| Phone call | Calling line (+...) | no | Phones a person; the voice settings hold the call. |
| Respond | none | no | How it answers. |
Validation, applied by the editor and the server:
| Message | Cause |
|---|---|
Give the step a title or a description. | Both are empty. |
The title is at most 120 characters. / The description is at most 1000 characters. | Length limits. |
Choose the tool this step uses. | An Action, Start workflow or Call an API step has no tool. |
List at least one e-mail address. | A Notify step has no valid address. |
The calling line is an international number (+...). | The Phone call reference is not + followed by 7 to 15 digits. |
The tools named by steps are added to the agent's allowed tools when it is saved.
Triggers tab
A trigger starts the bot without a person asking. Each runs as a chosen user who may run agents, with a per-hour limit. Run now (the play control) starts the bot with a test event; the bot really runs and approvals still apply.
| Trigger | Fields | Behaviour |
|---|---|---|
A record changes (RECORD) | Entity; Only when field (optional) and Equals; Created, updated, deleted | Fires on the selected changes, optionally only when a field has the value. |
A value crosses a limit (THRESHOLD) | Entity; Field; Is (<, <=, >, >=, =, !=); Limit | Fires once when a record starts to match, for example stock below 10, not once per change. |
On a schedule (SCHEDULE) | Every (minutes, 15 or more) or Daily at (HH:mm, UTC) | |
An outside system calls (WEBHOOK) | none | Shows a secret address another system posts JSON to. The address works without a sign-in at the gateway and answers 202 at once. |
A document is uploaded (DOCUMENT) | Document type (optional) | |
A call ended (CALL_ENDED) | Only with outcome (optional) | Fires when a voice agent's call ended, optionally with one outcome. |
All triggers accept What the bot should do (optional), the message the bot receives. Recent runs lists the latest runs of the bot's triggers.
Voice tab and Test tab
The Voice tab is the voice settings of the agent (see Voice settings). The Test tab chats with the bot and shows the steps it takes.
Permissions
Reading and designing bots uses the agent permissions (resource agent). Triggers run as the user chosen on the trigger; that user needs the right to run agents and the entity rights the tools use. Tools never exceed the person's own access.
API and CLI
| Action | Endpoint |
|---|---|
| List bots, templates | GET /api/v1/agents/bots, GET /api/v1/agents/bots/templates |
| Draft with AI | POST /api/v1/agents/bots/draft |
| Triggers | GET, POST /api/v1/agents/bots/{agentCode}/triggers; PUT, DELETE .../triggers/{id}; POST .../triggers/{id}/run |
| Runs | GET /api/v1/agents/bots/{agentCode}/runs?limit= |
| Make record tools | POST /api/v1/tools/from-entity |
CLI operations: agent-list, agent-get, agent-save, agent-update, agent-publish, agent-run.
Voice and calls
Where to find it
Workspace > AI Studio > Voice and calls. Page key ai-voice. The same voice settings also appear on the Voice tab of the Bot designer and of the Agent designer.
Summary
Tiles: Calls (with inbound and outbound counts), Completed (share, with failed), Transferred, Average call, First words (average wait for the agent) and Verified (share of verification attempts that passed). Four tabs: Calls, Analytics, Phone lines, Campaigns.
Calls tab
| Control | Description |
|---|---|
| Agent, Status | Filters (up to 100 calls shown). |
| Call row | Status, time, agent, outcome. |
| Call detail | Summary (or No summary (nothing was said, or no summary model answered). or The call is still going.), outcome, sentiment, follow-ups, the transcript (turns, scrollable), recordings (only when the caller consented), and the person's earlier calls. |
| Place a call | Agent, Number (+...), Name, What the call is about. Refused with Choose the agent and give an international number (+...). unless the number matches + and 7 to 15 digits. |
Phone lines tab
A line ties a phone number to an answering agent.
| Field | Description |
|---|---|
| Provider | Twilio is the supported provider. |
| Number (+...) | The line's number. |
| Answered by | An agent that has voice switched on. |
| Calls run as (user) | The user whose rights the call uses. |
| Account (Twilio Account SID) | The provider account. |
| Credential (auth token) | Stored encrypted and never shown again. |
| Calls per hour | Limit. |
| Also calls out | Allows outbound calls on this line. |
Each line shows the incoming-call webhook to enter at the provider (POST). Provider webhooks are checked against the provider's signature. If the provider must reach a different address from the one Studio uses, set ERP_PUBLIC_BASE_URL on the server.
Campaigns tab
Outbound calls to a list of people by an agent, inside a calling window in a time zone, with retries.
| Field | Description |
|---|---|
| Name | Required. |
| Voice agent | An agent with voice switched on. |
| Calling line | +..., optional. |
| What the calls are about | Context for the agent. |
| Time zone, From, To, Days | The calling window, for example 09:00 to 18:00 on MON,TUE,WED,THU,FRI. |
| Repeat | Once, daily or weekly. |
| Tries each | Attempts per person. |
| At once | Calls in parallel. |
| People | One per line: number, name, what to say about them, for example +919830012345, Asha Roy, invoice INV-1042 of 12,500 overdue 45 days. Lines that do not start with an international number are refused: These lines do not start with an international number (+...): .... |
Campaign statuses: ACTIVE, PAUSED, DONE. Start is offered unless the campaign is active or done, Pause while active, Finish until done. Each person has a status, the number of tries and the outcome.
Voice settings
Settings of one agent. Saving applies to calls at once and becomes part of the next agent version.
| Section | Fields |
|---|---|
| Speech | Speech to text and Text to speech: your own model profiles (OpenAI-style, Azure, Sarvam for Indian languages). Voice (the provider's name for it). Speed, 0.5 to 2 in steps of 0.05. |
| Languages | First language; Languages it may speak; Detect the caller's language. Codes look like en-IN. |
| Personality | Name it gives; Tone; Speaking style. Each at most 600 characters. |
| Lines it says | Greeting; Asking to record; When it did not understand; Goodbye. Each at most 600 characters. |
| Calls and results | Mode: People call or talk to it (ASSISTANT), It calls people (AGENT), It calls people and the result goes back into the ERP (AUTOMATION). Call outcomes (for example Promise to pay, Dispute); Fields to note (for example promise_date, amount); Caller may speak over it; Pause that ends a turn (seconds, default 2); Longest call (minutes, default 15). |
| Caller verification | See below. |
| Confirming actions | A spoken yes approves: NONE, LOW, MEDIUM (default) or HIGH risk actions; riskier ones wait for a person's approval. |
| Transfer to a person | The caller can ask for a person; Number or sip: address; Team (hand-over inbox); What it says first. |
| Recording | Keep transcripts; Keep audio (with consent); Keep for (days, default 90). Audio is kept only when the caller agrees; transcripts are kept for the same time. |
Caller verification
| Method | What the caller does |
|---|---|
Caller's number (CALLER_ID) | The record is found by the calling number (phone only). Put it first so a code, PIN or questions follow. |
Code by text message (OTP) | A six-digit code is sent to the registered number. |
Id and PIN (PIN) | The caller says their id and PIN. |
Id and questions (KNOWLEDGE) | The caller says their id and answers from their record, for example a date of birth. Up to 3 fields. |
Checks run in the order ticked. The caller's number alone proves nothing sensitive, so it must be followed by another check: The caller's number alone proves nothing sensitive: add a code by text message, a PIN or questions after it. and Put the caller's number first: the check after it is what proves who is calling. Records are looked up as the line's user, so entity access applies. Only hashes of the expected answers are kept during the call.
Validation messages: Choose how callers prove who they are., Name the entity callers are looked up in., Name the field with the caller's registered phone number., PIN checks need the id field and the PIN field., Knowledge questions need the id field and at least one field to ask about., "<name>" is not a field name (letters, digits and _)., The transfer number is an international number (+...) or a sip: address.
Talk to the agent
The Test control on the Voice tab records one utterance in the browser, stops on the agent's pause length and plays each sentence as it arrives; speaking over the agent stops it. It shows the time to the first words. If the microphone is unavailable you can type instead. Browser voice is one utterance at a time over HTTP, not a streaming audio connection.
API and CLI
| Action | Endpoint | CLI operation |
|---|---|---|
| Providers, lines | GET /api/v1/voice/providers, GET, POST /api/v1/voice/lines, PUT, DELETE .../lines/{id} | voice-lines |
| Place a call | POST /api/v1/voice/calls | |
| Calls | GET /api/v1/voice/sessions, GET .../sessions/{id}, GET .../sessions/{id}/turns/{seq}/audio | voice-calls, voice-call |
| Analytics | GET /api/v1/voice/analytics | voice-analytics |
| Campaigns | GET, POST /api/v1/voice/campaigns, POST .../campaigns/{id}/people, GET .../campaigns/{id}/people, POST .../campaigns/{id}/{start|pause|finish}, DELETE .../campaigns/{id} | voice-campaigns |
| Browser sessions | POST /api/v1/voice/sessions, POST .../sessions/{id}/turn, POST .../sessions/{id}/end | |
| Speak a line | POST /api/v1/voice/speak | |
| Provider webhooks | POST /api/v1/public/voice/{key}/incoming, turn, status, recording |
Limits and behaviour
- Recordings are stored in document management with only a file id in the call record, and removed after the agent's retention days.
- After each call the platform writes a summary, outcome, sentiment and follow-ups, and announces
VoiceCallEnded, which can start a bot. - Twilio is the only phone provider. There is no hold or conference.
- A transfer notes the reason on the call; the summary follows within seconds, after the transfer has started.
Related
Build a bot, AI Studio operations and safety, Reach customers with journeys, Store large files and play video and audio.