> ## 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. # Get AI Assistant > Fetches a single assistant by ID. Returns the full internal assistant configuration including variant config, agent identity, callSettings, analysisPlan, and knowledgeBase. ## OpenAPI ````yaml https://api.voice-agents.miraiminds.co/swagger.yaml get /v1/admin/assistant/get/{assistantId} 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/get/{assistantId}: get: tags: - Assistant summary: Get AI Assistant description: > Fetches a single assistant by ID. Returns the full internal assistant configuration including variant config, agent identity, callSettings, analysisPlan, and knowledgeBase. operationId: adminGetAssistant parameters: - $ref: '#/components/parameters/PublicKeyHeader' - $ref: '#/components/parameters/PrivateKeyHeader' - $ref: '#/components/parameters/WorkspaceHeader' - name: assistantId in: path required: true schema: type: string responses: '200': description: Assistant fetched successfully content: application/json: schema: $ref: '#/components/schemas/AssistantAdminGetResponse' example: message: Assistant fetched successfully data: _id: 69a57cdba3f3ab7e07cca1e4 name: My Abandoned Cart Assistant variant: type: abandoned_cart config: inputSchema: - name: id type: string isRequired: false - name: abandonedCheckoutUrl type: string isRequired: true - name: customer type: object isRequired: true fields: - name: firstName type: string isRequired: true - name: lastName type: string isRequired: false - name: email type: string isRequired: false - name: phone type: string isRequired: false - name: totalDiscountSet type: object isRequired: false fields: - name: shopMoney type: object isRequired: false fields: - name: amount type: string isRequired: true - name: totalLineItemsPriceSet type: object isRequired: true fields: - name: shopMoney type: object isRequired: true fields: - name: amount type: string isRequired: true - name: subtotalPriceSet type: object isRequired: true fields: - name: shopMoney type: object isRequired: true fields: - name: amount type: string isRequired: true - name: totalPriceSet type: object isRequired: true fields: - name: shopMoney type: object isRequired: true fields: - name: amount type: string isRequired: true - name: lineItems type: array isRequired: true fields: - name: title type: string isRequired: true - name: quantity type: number isRequired: true - name: variant type: object isRequired: true fields: - name: id type: string isRequired: true - name: title type: string isRequired: true - name: note type: string isRequired: false - name: shippingAddress type: object isRequired: true fields: - name: country type: string isRequired: true - name: address1 type: string isRequired: true - name: address2 type: string isRequired: false - name: city type: string isRequired: true - name: zip type: string isRequired: true - name: province type: string isRequired: true abandoned_cart: paymentPlan: mode: online agent: identity: name: neha gender: female voice: neha systemPrompt: '' icpContext: targetAgeGroups: - millennials locationTiers: - metro_urban language: english targetAudience: - female callSettings: slots: - startTime: '10:00' endTime: '17:30' maxCallDuration: 200 concurrentCallCount: 5 retryProtocol: maxAttemptsNoPickup: 2 maxAttemptsLowEngagement: 1 reAttemptPeriod: 300 maxRescheduleCount: 1 analysisPlan: successCriteriaPlan: >- You are a professional order intent evaluator. Analyze the call recording and return true ONLY when ALL these conditions are met: 1) Customer explicitly confirms they want to place/proceed with the order (e.g., "yes, place it", "confirm the order", "go ahead") 2) Total price/amount was clearly discussed AND customer explicitly agreed to it 3) Customer selects or confirms payment method (COD or prepaid) Return false if: - Customer is "just inquiring", "checking", "thinking about it", or "will let you know" - Price not mentioned, customer objects to price, or asks for more discount after final price - Customer says "already ordered", "will order online myself", or "order later" - Call disconnected before explicit order confirmation - Intent is ambiguous or customer gives vague responses Note: Address validation is handled separately. If customer confirms order intent without mentioning address, they may be using an address already in context. When in doubt, return false. summaryPlan: >- Provide a concise summary of the conversation, customer objections, and the outcome callInsightPlan: callConnected: type: boolean description: >- You are a professional call status evaluator. Analyze the attached call recording and return true only if a live person answered and there was real two-way conversation. If the call went to voicemail, automated message, IVR, ring-tone, greeting, silence, or anything without a live response, return false. Output only true or false. required: true customerEngaged: type: boolean description: >- You are a professional conversation engagement evaluator. Analyze the attached call recording and return true only if the customer did not disconnect abruptly at the beginning and continued engaging in the conversation for at least a few meaningful exchanges; otherwise return false. Output only true or false. required: true knowledgeBase: documents: - url: https://example.com/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. archivedAt: null createdAt: '2026-03-02T12:04:43.086Z' timezone: UTC '404': description: Assistant not found 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: AssistantAdminGetResponse: type: object properties: message: type: string example: Assistant fetched successfully data: $ref: '#/components/schemas/AssistantDetailResponse' 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 ````