> ## Documentation Index > Fetch the complete documentation index at: https://docs.miraiminds.co/llms.txt > Use this file to discover all available pages before exploring further. # List AI Assistants > Returns all assistants in the current workspace. Each item carries the **same payload** as the get-by-id endpoint (`GET /v1/admin/assistant/get/{assistantId}`), so no field selection is needed. Takes no query parameters or request body. ## OpenAPI ````yaml https://api.voice-agents.miraiminds.co/swagger.yaml get /v1/admin/assistant/list openapi: 3.0.3 info: title: Voice Agent by Mirai Minds version: 1.1.0 description: > Build AI voice assistants that call your customers or handle inbound calls — no telephony expertise required. ## Authentication Every request (except `/health`) requires two headers: - `x-public-key` — your public key - `x-private-key` — your private key Workspace-scoped endpoints also need a `workspace` header with the workspace `_id` returned on onboarding. ## Entity Hierarchy ``` Organization └── Workspace (holds assistants + telephony numbers) └── Assistant ├── Telephony (inbound + outbound phone numbers) ├── Knowledge Base (documents + FAQ for RAG) └── Analysis Plan (post-call AI evaluation) ``` ## Quick Start (5 minutes) 1. **Create a workspace** — `POST /v2/workspace/onboard/custom` → A default telephony number is auto-assigned in production. 2. **Create an assistant** — `POST /v1/admin/assistant/create` → Use `variant.type: custom` and write your `agent.systemPrompt`. 3. **Make a call** — `POST /v2/call/initiate` → Pass `callbackUrl` to receive real-time webhook events. See the **Onboarding** tag below for the full step-by-step guide. contact: name: API Architecture Team url: https://miraiminds.co license: name: Mirai Minds Proprietary License url: >- https://github.com/MiraiMinds/voice-agent-integration-specs/blob/main/LICENSE.md servers: - url: https://api.voice-agents.miraiminds.co description: Production Server - url: https://api.stage.voice-agent.miraiminds.co description: Staging Server - url: http://localhost:3000 description: Local Server security: - PublicKeyAuth: [] PrivateKeyAuth: [] tags: - name: Onboarding description: > Create and configure a workspace. **Custom is the recommended path** for all non-Shopify integrations. --- ## Complete Onboarding Flow (Custom) ### Step 1 — Create a workspace ```bash curl -X POST https://api.voice-agents.miraiminds.co/v2/workspace/onboard/custom \ -H "x-public-key: YOUR_PUBLIC_KEY" \ -H "x-private-key: YOUR_PRIVATE_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Support Line", "currencyCode": "USD", "timezone": "America/New_York", "supportContacts": { "phoneNumber": "+14155550100", "email": "support@acme.com" }, "trustSignals": { "valuePropositionOneLiner": "Premium 24x7 AI support for Acme customers." } }' ``` **Response:** ```json { "message": "Workspace onboarded successfully.", "data": { "_id": "6690a1b2c3d4e5f600000002", "name": "Acme Support Line", "variant": "custom" } } ``` > **Auto-assigned number**: In production, every new workspace is automatically assigned a default telephony number. Check your assigned number via the Telephony APIs. --- ### Step 2 — Create an assistant Use the workspace `_id` from Step 1 as the `workspace` header value. ```bash curl -X POST https://api.voice-agents.miraiminds.co/v1/admin/assistant/create \ -H "x-public-key: YOUR_PUBLIC_KEY" \ -H "x-private-key: YOUR_PRIVATE_KEY" \ -H "workspace: 6690a1b2c3d4e5f600000002" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Support Assistant", "variant": { "type": "custom" }, "agent": { "identity": { "name": "Priya", "gender": "female", "voice": "priya" }, "systemPrompt": "You are Priya, a helpful support agent for Acme. The customer name is {{customerName}}. Resolve their issue politely and professionally." }, "icpContext": { "language": "english" }, "callSettings": { "slots": [{ "startTime": "09:00", "endTime": "18:00" }], "maxCallDuration": 300, "concurrentCallCount": 5, "retryProtocol": { "maxAttemptsNoPickup": 2, "maxAttemptsLowEngagement": 1, "reAttemptPeriod": 300, "maxRescheduleCount": 1 } }, "analysisPlan": { "successCriteriaPlan": "Return true only if the customer issue was fully resolved and the customer expressed satisfaction. Return false if they were still confused, unhappy, or escalated.", "summaryPlan": "Summarize the customer issue, the resolution provided, and the customer sentiment." } }' ``` **Response:** ```json { "message": "Assistant created successfully", "data": { "assistantId": "69a57cdba3f3ab7e07cca1e4" } } ``` > **Number auto-assignment**: The workspace default number is auto-assigned as `outbound` on the **first** assistant in the workspace. Additional assistants need numbers assigned explicitly via the `telephony` field in the create/update payload. --- ### Step 3 — (Optional) Purchase a dedicated inbound number Search for available numbers: ```bash curl "https://api.voice-agents.miraiminds.co/v1/number-pool/search?countryCode=US&limit=5" \ -H "x-public-key: YOUR_PUBLIC_KEY" \ -H "x-private-key: YOUR_PRIVATE_KEY" \ -H "organization: YOUR_ORG_ID" ``` Purchase it: ```bash curl -X POST https://api.voice-agents.miraiminds.co/v1/number-pool/purchase \ -H "x-public-key: YOUR_PUBLIC_KEY" \ -H "x-private-key: YOUR_PRIVATE_KEY" \ -H "organization: YOUR_ORG_ID" \ -H "Content-Type: application/json" \ -d '{ "number": "+14155550101", "countryCode": "US", "numberType": "local" }' ``` Assign to assistant (inbound = customers call in, outbound = caller ID for outgoing calls): ```bash curl -X PUT https://api.voice-agents.miraiminds.co/v1/admin/assistant/update/69a57cdba3f3ab7e07cca1e4 \ -H "x-public-key: YOUR_PUBLIC_KEY" \ -H "x-private-key: YOUR_PRIVATE_KEY" \ -H "workspace: 6690a1b2c3d4e5f600000002" \ -H "Content-Type: application/json" \ -d '{ "telephony": { "inbound": "6700a1b2c3d4e5f600000111", "outbound": "6700a1b2c3d4e5f600000222" } }' ``` --- ### Step 4 — Make your first call ```bash curl -X POST https://api.voice-agents.miraiminds.co/v2/call/initiate \ -H "x-public-key: YOUR_PUBLIC_KEY" \ -H "x-private-key: YOUR_PRIVATE_KEY" \ -H "workspace: 6690a1b2c3d4e5f600000002" \ -H "Content-Type: application/json" \ -d '{ "phoneNumber": "+14155550200", "assistant": "69a57cdba3f3ab7e07cca1e4", "callbackUrl": "https://yourapp.com/webhooks/call-events", "payload": { "customerName": "Alex" } }' ``` - name: Assistant description: > Assistants are the core of the platform. Each assistant has: - An **identity** (name, voice, gender) - A **systemPrompt** (the AI's instructions) - **Telephony** config (inbound/outbound numbers) - A **Knowledge Base** (documents + FAQ for RAG retrieval) - An **analysisPlan** (post-call AI evaluation) - **callSettings** (scheduling, retry logic, concurrency) --- ## Variant Types | Variant | Use case | systemPrompt | |---------|----------|--------------| | `custom` | Any use case you define | Required — you author it | | `abandoned_cart` | Shopify cart recovery | Auto-generated — leave empty | | `cod_to_prepaid` | Convert Shopify COD orders to prepaid | Auto-generated — leave empty | | `address_verification` | Verify or collect Shopify shipping addresses | Auto-generated — leave empty | | `order_confirmation` | Confirm Shopify orders before fulfillment | Auto-generated — leave empty | | `ndr_followup` | Follow up on failed delivery / NDR events | Auto-generated — leave empty | ## Using Preset Variants 1. Create the assistant with `variant.type` set to the preset variant and leave `agent.systemPrompt` empty. 2. Put preset configuration under `variant.config.`. 3. Initiate calls with `payload` fields that match the variant input schema. Shopify order variants use Shopify order-like payloads; `ndr_followup` uses courier NDR data. Config quick reference: - `cod_to_prepaid`: requires `paymentLinkValidity`, `codFee`, and `supportContacts`. - `address_verification`: requires `minDays`, `maxDays`, and `supportContacts`. - `order_confirmation`: optional `supportContacts`. - `ndr_followup`: optional `maxRescheduleDays`, `webhookToken`, and `supportContacts`. Shiprocket can post NDR events to `POST /v1/shiprocket/ndr-webhook/{assistantId}`; when `webhookToken` is set, send the same value in `x-api-key`. --- ## Using the Knowledge Base (RAG) The knowledge base lets the assistant retrieve information from your uploaded documents and FAQ during a live call. ### 1. Upload a document See the **Knowledge Base** tag for the full 3-step upload flow. After upload + processing, you get a file URL. ### 2. Link to the assistant Pass the file URL under `knowledgeBase.documents` when creating or updating the assistant: ```json { "knowledgeBase": { "documents": [ { "url": "https://storage.miraiminds.co/kb/acme-product-catalog.pdf", "title": "Product Catalog", "type": "pdf" } ], "faq": [ { "question": "What is your return policy?", "answer": "We offer a 7-day return policy for unused items in original packaging." }, { "question": "How long does shipping take?", "answer": "Standard shipping is 3–5 business days." } ] } } ``` ### 3. Tell the assistant to use it in systemPrompt ``` You are Priya, a support agent for Acme. When a customer asks about products, pricing, policies, or shipping: 1. Search the knowledge base first. 2. Use the retrieved information to answer accurately. 3. If you cannot find the answer, say: "I don't have that detail right now — let me connect you with a specialist." Never make up information that is not in the knowledge base. Always greet the customer as {{customerName}}. ``` --- ## Using analysisPlan `analysisPlan` instructs the AI to evaluate each call after it ends. Results appear in the `end-of-call` webhook event and the call dashboard. | Field | Type | Purpose | |-------|------|---------| | `successCriteriaPlan` | string prompt | AI returns `true`/`false` — was the goal achieved? | | `summaryPlan` | string prompt | AI returns a plain-English summary of the call | | `callInsightPlan` | object | AI returns structured key/value insights you define | ### Example — Customer Support ```json { "analysisPlan": { "successCriteriaPlan": "Return true ONLY if the customer issue was fully resolved and they expressed satisfaction before ending the call. Return false if they were still confused, frustrated, or requested a callback to a human agent.", "summaryPlan": "Summarize: (1) the customer issue, (2) the solution provided, (3) customer sentiment (positive/neutral/negative), and (4) any follow-up action needed.", "callInsightPlan": { "issueResolved": { "type": "boolean", "description": "Was the customer issue fully resolved during the call?", "required": true }, "escalationRequested": { "type": "boolean", "description": "Did the customer ask to speak with a human agent?", "required": true }, "customerSentiment": { "type": "string", "description": "Overall customer sentiment at end of call", "required": true, "enum": ["positive", "neutral", "negative"] } } } } ``` ### Example — Appointment Booking ```json { "analysisPlan": { "successCriteriaPlan": "Return true ONLY if an appointment was confirmed with a specific date and time agreed by both parties. Return false for all other outcomes.", "summaryPlan": "Summarize: the appointment date, time, service type, and any special instructions the customer provided.", "callInsightPlan": { "appointmentBooked": { "type": "boolean", "description": "Was an appointment successfully booked?", "required": true }, "appointmentDate": { "type": "string", "description": "The confirmed appointment date (format: YYYY-MM-DD)", "required": false } } } } ``` --- ## Inbound Calls To handle inbound calls, assign a telephony number to `telephony.inbound`. When a customer calls that number, the assistant answers automatically. ```json { "telephony": { "inbound": "6700a1b2c3d4e5f600000111", "outbound": "6700a1b2c3d4e5f600000222" } } ``` > Each inbound number can only be assigned to **one** assistant at a time. Assigning it to a new assistant automatically removes it from the previous one. - name: Knowledge Base description: > Upload documents so your assistant can answer questions from its own knowledge during a call (RAG — Retrieval-Augmented Generation). **Supported file types:** PDF, TXT, DOCX, Markdown **Max file size:** 100 MB **Max chunk size:** 10 MB per chunk --- ## Upload Flow (3 steps) Files are uploaded in chunks to handle network interruptions gracefully. ### Step 1 — Start an upload session ```bash curl -X POST https://api.voice-agents.miraiminds.co/v1/knowledge-base/upload/start \ -H "x-public-key: YOUR_PUBLIC_KEY" \ -H "x-private-key: YOUR_PRIVATE_KEY" \ -H "workspace: YOUR_WORKSPACE_ID" \ -H "Content-Type: application/json" \ -d '{ "fileName": "product-catalog.pdf", "totalChunks": 1, "fileSize": 524288, "mimeType": "application/pdf" }' ``` **Response:** ```json { "message": "Upload session created successfully.", "sessionId": "sess_abc123xyz" } ``` ### Step 2 — Upload each chunk Repeat for each chunk (start at `chunkIndex: 0`): ```bash curl -X POST https://api.voice-agents.miraiminds.co/v1/knowledge-base/upload/chunk/sess_abc123xyz \ -H "x-public-key: YOUR_PUBLIC_KEY" \ -H "x-private-key: YOUR_PRIVATE_KEY" \ -H "workspace: YOUR_WORKSPACE_ID" \ -F "chunk=@product-catalog.pdf" \ -F "chunkIndex=0" ``` **Response:** ```json { "message": "Chunk uploaded successfully." } ``` ### Step 3 — Complete the upload ```bash curl -X POST https://api.voice-agents.miraiminds.co/v1/knowledge-base/upload/complete/sess_abc123xyz \ -H "x-public-key: YOUR_PUBLIC_KEY" \ -H "x-private-key: YOUR_PRIVATE_KEY" \ -H "workspace: YOUR_WORKSPACE_ID" ``` **Response:** ```json { "message": "Upload completed. Processing has started in the background.", "sessionId": "sess_abc123xyz", "knowledgeBaseId": "6701a1b2c3d4e5f600000050", "knowledgeBaseStatus": "processing" } ``` Processing is asynchronous. Poll `GET /v1/knowledge-base/files/{knowledgeBaseId}` until `status` is `ready`, then link the file to your assistant. --- ## What to Write in systemPrompt to Trigger Knowledge Base Retrieval ``` You are a support agent for Acme. When a customer asks about products, pricing, policies, or shipping: 1. Search the knowledge base first. 2. Answer using only information found in the knowledge base. 3. If the answer is not in the knowledge base, say: "I don't have that detail right now — let me connect you with a specialist." Never make up information. Always be accurate. ``` - name: Telephony description: > Manage phone numbers for outbound and inbound calls. - **Outbound**: caller ID used when the assistant places a call to a customer - **Inbound**: the number customers dial to reach the assistant --- ## Using an Existing (Auto-Assigned) Number Every new workspace gets a default telephony number assigned automatically in production. Retrieve it and assign it to your assistant's `telephony.outbound` or `telephony.inbound`. --- ## Purchasing a New Number and Assigning to an Assistant ### Step 1 — Search available numbers ```bash curl "https://api.voice-agents.miraiminds.co/v1/number-pool/search?countryCode=US&numberType=local&limit=5" \ -H "x-public-key: YOUR_PUBLIC_KEY" \ -H "x-private-key: YOUR_PRIVATE_KEY" \ -H "organization: YOUR_ORG_ID" ``` **Response:** ```json { "data": [ { "number": "+14155550101", "countryCode": "US", "numberType": "local", "monthlyRateCents": 100 }, { "number": "+14155550102", "countryCode": "US", "numberType": "local", "monthlyRateCents": 100 } ] } ``` ### Step 2 — Purchase a number ```bash curl -X POST https://api.voice-agents.miraiminds.co/v1/number-pool/purchase \ -H "x-public-key: YOUR_PUBLIC_KEY" \ -H "x-private-key: YOUR_PRIVATE_KEY" \ -H "organization: YOUR_ORG_ID" \ -H "Content-Type: application/json" \ -d '{ "number": "+14155550101", "countryCode": "US", "numberType": "local" }' ``` **Response** (contains `_id` for use in assistant `telephony`): ```json { "data": { "_id": "6700a1b2c3d4e5f600000111", "number": "+14155550101", "status": "active" } } ``` ### Step 3 — Assign to an assistant Use the `_id` from Step 2: ```bash curl -X PUT https://api.voice-agents.miraiminds.co/v1/admin/assistant/update/YOUR_ASSISTANT_ID \ -H "x-public-key: YOUR_PUBLIC_KEY" \ -H "x-private-key: YOUR_PRIVATE_KEY" \ -H "workspace: YOUR_WORKSPACE_ID" \ -H "Content-Type: application/json" \ -d '{ "telephony": { "inbound": "6700a1b2c3d4e5f600000111", "outbound": "6700a1b2c3d4e5f600000222" } }' ``` > **Inbound exclusivity**: Each inbound number can only be held by one assistant at a time. Assigning it to a new assistant automatically removes it from the previous one. - name: Call description: > ## Outbound Calls Use `POST /v2/call/initiate` to trigger an outbound call to a customer. The assistant calls the number, runs the conversation, and fires webhook events to your `callbackUrl`. --- ## Inbound Calls Assign a telephony number to `telephony.inbound` on an assistant. When a customer dials that number, the assistant picks up automatically. No API call required — just the number assignment. ``` Customer dials +14155550101 → Number is linked to "Acme Support" assistant → Assistant picks up and follows its systemPrompt → Call events fire to your callbackUrl (if configured) ``` --- ## Webhook Events Reference Register a `callbackUrl` on `POST /v2/call/initiate` to receive real-time call events. ### Event Payload Shape ```json { "event": { "type": "", "data": { ... } } } ``` ### Call Lifecycle Events | Event | When | What to do | |-------|------|-----------| | `call.initiate` | Call has been queued | Log that the call started | | `call.in-progress` | Customer answered, conversation started | Start session timer | | `call.ended` | Call hung up, analysis running | Update call record to pending | | `call.completed` | Call done + analysis complete | Read `analysis.success` and `analysis.summary` | | `call.timeout` | Call exceeded `maxCallDuration` | Flag for manual review | | `call.failed` | Network/telephony error | Retry or alert your team | | `call.busy` | Customer line was busy | Schedule retry | | `call.no-answer` | Rang with no answer | Schedule retry | | `call.skip` | Call skipped (outside allowed hours, etc.) | Log and continue | | `call.rescheduled` | Customer asked to be called back | Wait for next attempt | | `call.aborted` | Call cancelled via `/v2/call/abort` | Stop tracking | | `call.validation-failed` | Payload validation failed before calling | Fix payload and resubmit | | `call.lifecycle-ended` | All retries exhausted — call is permanently done | Final status update | | `end-of-call` | Same as `call.completed` with full analysis included | Primary event for reading results | | `action` | Assistant triggered a business action mid-call | Execute the action in your system | ### `end-of-call` Payload Example ```json { "event": { "type": "end-of-call", "data": { "call": { "id": "call_6701abc123", "status": "completed", "startedAt": "2026-06-30T10:00:00.000Z", "endedAt": "2026-06-30T10:05:32.000Z", "durationSeconds": 332, "recordingUrl": "https://storage.miraiminds.co/.../recording.wav", "detailUrl": "https://app.miraiminds.co/calls/call_6701abc123" }, "analysis": { "success": true, "summary": "Customer called about a delayed order. Issue resolved — package was confirmed dispatched. Customer was satisfied.", "insights": { "issueResolved": true, "escalationRequested": false, "customerSentiment": "positive" } }, "credits": { "used": 2.5, "available": 97.5 } } } } ``` ### `action` Event Payload Example ```json { "event": { "type": "action", "data": { "action": "create_order", "call": { "id": "call_6701abc123" }, "payload": { "email": "alex@example.com", "phone": "+14155550200", "lineItems": [{ "title": "Blue Sneakers", "quantity": 1 }], "cartTotal": 99.99 } } } } ``` **Available action types:** `create_order`, `send_whatsapp`, `mark_prepaid`, `update_address`, `confirmed_address` - name: Setting description: Platform health and maintenance status. - name: Organization description: Archive and unarchive organizations and workspaces. - name: Voice Gallery description: List available AI voices for use in assistant configuration. - name: Showcase description: Real call recordings and use-case flow demos. paths: /v1/admin/assistant/list: get: tags: - Assistant summary: List AI Assistants description: > Returns all assistants in the current workspace. Each item carries the **same payload** as the get-by-id endpoint (`GET /v1/admin/assistant/get/{assistantId}`), so no field selection is needed. Takes no query parameters or request body. operationId: adminListAssistants parameters: - $ref: '#/components/parameters/PublicKeyHeader' - $ref: '#/components/parameters/PrivateKeyHeader' - $ref: '#/components/parameters/WorkspaceHeader' responses: '200': description: Assistants fetched successfully content: application/json: schema: type: object properties: message: type: string example: Assistants fetched successfully data: type: array items: $ref: '#/components/schemas/AssistantDetailResponse' components: parameters: PublicKeyHeader: name: x-public-key in: header required: true schema: type: string PrivateKeyHeader: name: x-private-key in: header required: true schema: type: string WorkspaceHeader: name: workspace in: header required: true schema: type: string schemas: AssistantDetailResponse: type: object properties: _id: type: string example: 69b954f86ee9a7796fa57891 name: type: string example: My Assistant variant: type: object properties: type: type: string enum: - abandoned_cart - cod_to_prepaid - address_verification - order_confirmation - ndr_followup - custom example: abandoned_cart config: $ref: '#/components/schemas/VariantConfigs' agent: type: object properties: identity: $ref: '#/components/schemas/AgentIdentity' systemPrompt: type: string firstMessage: type: string description: The first message the assistant speaks when the call connects. endMessage: type: string description: The message the assistant speaks just before ending the call. tools: type: array items: $ref: '#/components/schemas/AgentTool' telephony: $ref: '#/components/schemas/AssistantTelephony' icpContext: $ref: '#/components/schemas/ICPContext' callSettings: $ref: '#/components/schemas/CallSettings' analysisPlan: $ref: '#/components/schemas/AnalysisPlan' knowledgeBase: $ref: '#/components/schemas/AdminKnowledgeBase' archivedAt: type: string format: date-time nullable: true example: null createdAt: type: string format: date-time example: '2026-03-17T13:19:52.297Z' timezone: type: string example: UTC VariantConfigs: type: object description: > Variant-specific configuration. For the **custom** variant, declare the dynamic variables your `agent.systemPrompt` references via `inputSchema`. For preset variants, provide the matching block under the variant type when that variant requires config. properties: inputSchema: type: array description: > **Used by the `custom` variant.** Declares the dynamic variables the assistant expects for a call. Each variable declared here can be referenced inside `agent.systemPrompt` using the `{{variableName}}` placeholder syntax (nested values via dot-paths, e.g. `{{customer.firstName}}`), and its value is supplied per call through `variableValues` when initiating the call. items: $ref: '#/components/schemas/AdditionalField' variableSchema: type: object description: >- Optional JSON-schema-style declaration of variables (alternative to `inputSchema`). properties: properties: type: object additionalProperties: type: object properties: type: type: string description: type: string required: type: array items: type: string abandoned_cart: type: object description: Required when variant type is `abandoned_cart`. properties: paymentPlan: type: object description: Payment plan configuration for the assistant. properties: mode: type: string enum: - online - cod - both description: Payment mode accepted by the store for this assistant. example: online additionalFee: type: object properties: cod: type: number description: Additional COD fee amount. example: 50 cod_to_prepaid: type: object description: Required when variant type is `cod_to_prepaid`. required: - paymentLinkValidity - codFee - supportContacts properties: paymentLinkValidity: type: number description: How long the prepaid payment link remains valid, in minutes. example: 30 codFee: type: number description: >- COD fee amount the assistant can mention as the prepaid-saving incentive. example: 50 supportContacts: $ref: '#/components/schemas/SupportContacts' address_verification: type: object description: Required when variant type is `address_verification`. required: - minDays - maxDays - supportContacts properties: minDays: type: number description: Minimum expected delivery timeline in days. example: 3 maxDays: type: number description: Maximum expected delivery timeline in days. example: 5 supportContacts: $ref: '#/components/schemas/SupportContacts' order_confirmation: type: object description: Optional when variant type is `order_confirmation`. properties: supportContacts: $ref: '#/components/schemas/SupportContacts' ndr_followup: type: object description: Optional when variant type is `ndr_followup`. properties: maxRescheduleDays: type: number minimum: 1 maximum: 7 description: >- Maximum number of days ahead the customer can reschedule delivery. example: 3 webhookToken: type: string description: >- Shared secret expected in the `x-api-key` header for Shiprocket NDR webhooks. example: shiprocket-secret supportContacts: $ref: '#/components/schemas/SupportContacts' AgentIdentity: type: object properties: name: type: string gender: type: string enum: - male - female voice: type: string AgentTool: type: object description: > Internal response representation of tools grouped by their integration. Create and update requests only need the tool `_id` values; the server builds this grouping automatically. required: - integration_id - tools properties: integration_id: type: string description: >- ObjectId of the integration the tools belong to (the `integration_id` from the tool response). example: 6710a1b2c3d4e5f600000010 tools: type: array description: >- ObjectIds of the tools to enable (each is a tool `_id`, e.g. from `POST /v1/admin/tool/api`). items: type: string example: - 6710a1b2c3d4e5f600000020 AssistantTelephony: type: object description: > Telephony numbers linked to the assistant. Each value is the `_id` of a telephony number (from `GET /v1/number-pool/{telephonyNumberId}` or `POST /v1/number-pool/purchase`). - `inbound` — the phone number customers call to reach this assistant. When someone dials it, the assistant picks up automatically and follows its `systemPrompt`. Only one assistant can hold an inbound number at a time; assigning it here removes it from any other assistant. - `outbound` — the caller ID shown to customers when the assistant places an outgoing call. **Auto-assignment**: In production, the first assistant in a new workspace automatically receives the workspace's default number as `outbound`. Additional assistants must be assigned numbers explicitly. properties: inbound: type: string nullable: true description: > `_id` of the telephony number used for inbound (incoming) calls. Customers dial this number to reach the assistant. example: 6700a1b2c3d4e5f600000111 outbound: type: string nullable: true description: > `_id` of the telephony number used as caller ID for outbound (outgoing) calls. example: 6700a1b2c3d4e5f600000222 ICPContext: type: object properties: targetAgeGroups: type: array items: type: string enum: - gen_z - millennials - gen_x - boomers description: Affects slang usage. Gen Z = 'Vibe'; Boomers = 'Quality'. locationTiers: type: array items: type: string enum: - metro_urban - tier1 - tier2 - tier3 - rural description: Affects language complexity and speed. language: type: string enum: - hinglish - english - hindi - telugu - tamil - kannada - malayalam - gujarati - punjabi - odia - marathi description: Affects language complexity and speed. targetAudience: type: array items: type: string enum: - male - female - children description: Affects language complexity and speed. CallSettings: type: object required: - slots - retryProtocol properties: slots: type: array description: Array of time slots for call execution minItems: 1 items: type: object properties: startTime: type: string example: '10:00' endTime: type: string example: '13:00' maxCallDuration: type: number example: 200 concurrentCallCount: type: number maximum: 10 example: 5 retryProtocol: $ref: '#/components/schemas/RetryProtocol' AnalysisPlan: type: object description: > Post-call AI evaluation configuration. After each call ends, the platform runs these prompts against the call recording and transcript. Results are returned in the `end-of-call` webhook event and visible in the call dashboard. properties: successCriteriaPlan: type: string description: > A prompt instructing the AI to return `true` or `false` based on whether the call objective was achieved. Write it as a precise instruction with explicit conditions. The AI evaluates the call recording and returns only `true` or `false`. example: >- Return true ONLY if the customer issue was fully resolved and they expressed satisfaction before ending the call. Return false if they were still confused, frustrated, or requested escalation. summaryPlan: type: string description: > A prompt instructing the AI to produce a plain-English summary of the call. Tell it what aspects to cover (e.g. issue, resolution, sentiment, next steps). example: >- Summarize: (1) the customer issue, (2) the solution provided, (3) customer sentiment (positive/neutral/negative), and (4) any follow-up action needed. callInsightPlan: $ref: '#/components/schemas/CallInsightPlan' AdminKnowledgeBase: type: object description: Combined knowledge base containing both documents and FAQ entries. properties: documents: type: array description: List of documents for deep knowledge retrieval. items: type: object required: - url - title - type properties: url: type: string format: uri title: type: string type: type: string enum: - pdf - txt - docx - markdown faq: type: array description: List of Question-Answer pairs. items: $ref: '#/components/schemas/faq' AdditionalField: type: object required: - name properties: name: type: string type: type: string enum: - string - number - boolean - object - array default: string isRequired: type: boolean fields: type: array items: $ref: '#/components/schemas/AdditionalField' SupportContacts: type: object properties: phoneNumber: type: string example: '+919876543210' email: type: string format: email example: support@example.com RetryProtocol: type: object description: Smart logic based on why the call failed. properties: maxAttemptsNoPickup: type: integer default: 2 description: Phone rang, no answer. Call back twice. maxAttemptsLowEngagement: type: integer default: 1 description: User picked up but said 'busy' or cut immediately. Call back once. reAttemptPeriod: type: integer default: 300 description: Delay between second reattempt of call to same person in seconds maxRescheduleCount: type: integer default: 1 maximum: 5 description: How many times we can reschedule a call when user ask to callback CallInsightPlan: type: object additionalProperties: $ref: '#/components/schemas/InsightField' description: Map of insight names to their expected structure. faq: type: object required: - question - answer properties: question: type: string example: What is your return policy? answer: type: string example: We offer a 7-day return policy for unused items. InsightField: type: object required: - type - description - required properties: type: type: string enum: - number - boolean - string description: type: string required: type: boolean enum: type: array items: type: string securitySchemes: PublicKeyAuth: type: apiKey in: header name: x-public-key PrivateKeyAuth: type: apiKey in: header name: x-private-key ````