> ## Documentation Index > Fetch the complete documentation index at: https://docs.voiceaiwrapper.app/llms.txt > Use this file to discover all available pages before exploring further. # Create Web Widget > Creates a new web widget for an inbound campaign. ## Authentication All requests require an `Authorization` header using Bearer token authentication: `Authorization: Bearer ` ## OpenAPI ````yaml POST /api/v2/web-widgets openapi: 3.1.0 info: title: VoiceAIWrapper API description: >- REST API for managing campaigns, leads, clients, web widgets, and voice providers on VoiceAIWrapper. license: name: MIT version: 1.0.0 servers: - url: https://api.voiceaiwrapper.app security: - bearerAuth: [] paths: /api/v2/web-widgets: post: tags: - Web Widgets summary: Create Web Widget description: >- Creates a new web widget for an inbound campaign. ## Authentication All requests require an `Authorization` header using Bearer token authentication: `Authorization: Bearer ` operationId: createWebWidget requestBody: required: true description: Web widget configuration content: application/json: schema: $ref: '#/components/schemas/CreateWebWidgetRequest' responses: '201': description: >- Web widget created successfully. Returns widget ID, campaign ID, and configuration. content: application/json: schema: type: object properties: status: type: string example: success message: type: string example: Web widget created successfully data: type: object properties: web_widget_id: type: string voice_campaign_id: type: string config: type: object created_at: type: string format: date-time '400': description: >- Invalid request data. Common causes: missing required fields, invalid config values, outbound campaign, or assistant validation failure. content: application/json: schema: $ref: '#/components/schemas/ErrorWithList' example: message: Invalid data errors: - 'campaign ID is missing: voice_campaign_id' '401': description: Authentication failed. Ensure the Bearer token is present and valid. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' '404': description: >- Resource not found. The voice_campaign_id does not exist or does not belong to your tenant. content: application/json: schema: $ref: '#/components/schemas/ErrorWithList' example: message: campaign not found or does not belong to this tenant errors: - Invalid voice_campaign_id '409': description: Conflict. A web widget already exists for this campaign. content: application/json: schema: $ref: '#/components/schemas/ErrorWithList' example: message: A web widget already exists for this campaign errors: - Duplicate web widget '500': description: Internal server error. Contact support if this persists. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' components: schemas: CreateWebWidgetRequest: type: object required: - voice_campaign_id - config properties: voice_campaign_id: type: string description: Global ID of the inbound campaign for this widget. Required. example: Vm9pY2VDYW1wYWlnbjoxMjM= voice_assistant_id: type: string description: >- Provider-native ID of the voice assistant. Required when config.mode includes 'voice'. example: asst_abc123 chat_assistant_id: type: string description: >- Provider-native ID of the chat assistant. Required when config.mode includes 'chat'. example: asst_chat123 config: type: object description: >- Widget appearance and behaviour configuration. Required. All fields inside config are optional and will use defaults if not provided. properties: mode: type: array items: type: string enum: - voice - chat description: >- Array of enabled interaction modes. Optional. Default: `["voice"]`. Valid values: `"voice"`, `"chat"`. default: - voice example: - voice style: type: string enum: - card - compact description: >- Widget style. Optional. Default: `"card"`. Valid values: `"card"`, `"compact"`. default: card example: card theme: type: string enum: - light - dark description: >- Color theme. Optional. Default: `"light"`. Valid values: `"light"`, `"dark"`. default: light example: light backgroundColor: type: string description: 'Background color in hex format. Optional. Default: `"#ffffff"`.' default: '#ffffff' example: '#ffffff' textColor: type: string description: 'Text color in hex format. Optional. Default: `"#000000"`.' default: '#000000' example: '#000000' accentColor: type: string description: 'Accent color in hex format. Optional. Default: `"#3b82f6"`.' default: '#3b82f6' example: '#3b82f6' ctaButtonColor: type: string description: 'CTA button color in hex format. Optional. Default: `"#3b82f6"`.' default: '#3b82f6' example: '#3b82f6' footerTextColor: type: string description: 'Footer text color in hex format. Optional. Default: `"#666666"`.' default: '#666666' example: '#666666' chatEndCallButtonColor: type: string description: >- Chat end call button color in hex format. Optional. Default: `"#ef4444"`. default: '#ef4444' example: '#ef4444' chatConnectedStatusColor: type: string description: >- Chat connected status indicator color in hex format. Optional. Default: `"#22c55e"`. default: '#22c55e' example: '#22c55e' animationStyle: type: string enum: - default - glob - siri description: >- Animation style for the widget. Optional. Default: `"default"`. Valid values: `"default"`, `"glob"`, `"siri"`. default: default example: default logo: type: string format: uri description: URL to the logo image displayed in the widget. Optional. example: https://example.com/logo.png icon: type: string enum: - activity - airplay - alertCircle - alertOctagon - alertTriangle - alignCenter - alignJustify - alignLeft - alignRight - anchor - aperture - archive - archiveRestore - arrowDown - arrowDownCircle - arrowDownLeft - arrowDownRight - arrowLeft - arrowLeftCircle - arrowLeftRight - arrowRight - arrowRightCircle - arrowUp - arrowUpCircle - arrowUpDown - arrowUpLeft - arrowUpRight - atSign - award - barChart - barChart2 - barChart3 - barChart4 - battery - batteryCharging - batteryFull - batteryLow - batteryMedium - bell - bellOff - bellRing - bike - binary - bluetooth - bluetoothConnected - bluetoothOff - bluetoothSearching - bold - book - bookOpen - bookmark - bot - box - briefcase - building - building2 - bus - calculator - calendar - calendarCheck - calendarClock - calendarDays - calendarHeart - calendarMinus - calendarOff - calendarPlus - calendarRange - calendarSearch - calendarX - camera - cameraOff - car - carrot - cast - check - checkCircle - checkCircle2 - checkSquare - checkSquare2 - chevronDown - chevronFirst - chevronLast - chevronLeft - chevronRight - chevronUp - chevronsDown - chevronsDownUp - chevronsLeft - chevronsLeftRight - chevronsRight - chevronsRightLeft - chevronsUp - chevronsUpDown - circle - circleDot - circleEllipsis - circleOff - circleSlashed - circleSlash - clipboard - clipboardCheck - clipboardCopy - clipboardEdit - clipboardList - clipboardSignature - clipboardType - clipboardX - clock - clock1 - clock10 - clock11 - clock12 - clock2 - clock3 - clock4 - clock5 - clock6 - clock7 - clock8 - clock9 - cloud - cloudCog - cloudDrizzle - cloudFog - cloudHail - cloudLightning - cloudMoon - cloudMoonRain - cloudOff - cloudRain - cloudRainWind - cloudSnow - cloudSun - cloudSunRain - cloudy - clover - code - code2 - coffee - cog - coins - columns - command - compass - component - conciergeBell - contact - contact2 - container - contrast - cookie - copy - copyleft - copyright - creditCard - croissant - crop - cross - crosshair - crown - cupSoda - currency - database - delete - dessert - diameter - diamond - dice1 - dice2 - dice3 - dice4 - dice5 - dice6 - dices - diff - disc - divide - divideCircle - divideSquare - dna - dnaOff - dog - dollarSign - download - downloadCloud - droplets - dumbbell - ear - earOff - edit - edit2 - edit3 - egg - eggFried - eggOff - equal - equalNot - eraser - euro - expand - externalLink - eye - eyeOff - factory - fan - fastForward - feather - file - fileArchive - fileAudio - fileAudio2 - fileAxis3d - fileBadge - fileBadge2 - fileBarChart - fileBarChart2 - fileBox - fileCheck - fileCheck2 - fileClock - fileCode - fileCode2 - fileCog - fileCog2 - fileDiff - fileDigit - fileDown - fileEdit - fileHeart - fileImage - fileInput - fileJson - fileJson2 - fileKey - fileKey2 - fileLineChart - fileLock - fileLock2 - fileMinus - fileMinus2 - fileOutput - filePieChart - filePlus - filePlus2 - fileQuestion - fileScan - fileSearch - fileSearch2 - fileSignature - fileSpreadsheet - fileSymlink - fileTerminal - fileText - fileType - fileType2 - fileUp - fileVideo - fileVideo2 - fileVolume - fileVolume2 - fileWarning - fileX - fileX2 - files - film - filter - fingerprint - fish - fishOff - flag - flagOff - flagTriangleLeft - flagTriangleRight - flame - flashlight - flashlightOff - flaskConical - flaskRound - flipHorizontal - flipHorizontal2 - flipVertical - flipVertical2 - flower - flower2 - focus - folder - folderArchive - folderCheck - folderClock - folderClosed - folderCog - folderCog2 - folderDown - folderEdit - folderHeart - folderInput - folderKey - folderLock - folderMinus - folderOpen - folderOutput - folderPlus - folderSearch - folderSearch2 - folderSymlink - folderTree - folderUp - folderX - folders - formInput - forward - frame - frown - fuel - functionSquare - gamepad - gamepad2 - gauge - gavel - gem - ghost - gift - gitBranch - gitBranchPlus - gitCommit - gitCompare - gitFork - gitMerge - gitPullRequest - globe - globe2 - grab - graduationCap - grape - grid - gripHorizontal - gripVertical - hammer - hand - handMetal - hardDrive - hardHat - hash - haze - headphones - headset - heart - heartCrack - heartHandshake - heartOff - heartPulse - helpCircle - hexagon - highlighter - history - home - hop - hopOff - hotel - hourglass - iceCream - iceCream2 - image - imageMinus - imageOff - imagePlus - import - inbox - indent - indianRupee - infinity - info - inspect - instagram - italic - japaneseYen - joystick - key - keyboard - lamp - lampCeiling - lampDesk - lampFloor - lampWallDown - lampWallUp - landmark - languages - laptop - laptop2 - lasso - lassoSelect - laugh - layers - layout - layoutDashboard - layoutGrid - layoutList - layoutTemplate - leaf - library - lifeBuoy - lightbulb - lightbulbOff - lineChart - link - link2 - link2Off - list - listChecks - listEnd - listMinus - listMusic - listOrdered - listPlus - listStart - listVideo - listX - loader - loader2 - locate - locateFixed - locateOff - lock - lockKeyhole - logIn - logOut - luggage - magnet - mail - mailCheck - mailMinus - mailOpen - mailPlus - mailQuestion - mailSearch - mailWarning - mailX - mails - map - mapPin - mapPinOff - martini - maximize - maximize2 - medal - megaphone - megaphoneOff - meh - menu - messageCircle - messageSquare - messagesSquare - mic - mic2 - micOff - microscope - milestone - milk - milkOff - minimize - minimize2 - minus - minusCircle - minusSquare - monitor - monitorOff - monitorSpeaker - moon - moreHorizontal - moreVertical - mountain - mountainSnow - mouse - mousePointer - mousePointer2 - mousePointerClick - move - move3d - moveHorizontal - moveVertical - music - music2 - music3 - music4 - navigation - navigation2 - navigation2Off - network - newspaper - octagon - option - outdent - package - package2 - packageCheck - packageMinus - packageOpen - packagePlus - packageSearch - packageX - paintBucket - paintbrush - paintbrush2 - palette - palmtree - paperclip - partyPopper - pause - pauseCircle - pauseOctagon - penTool - percent - personStanding - phone - phoneCall - phoneForwarded - phoneIncoming - phoneMissed - phoneOff - phoneOutgoing - pi - piSquare - pictureInPicture - pictureInPicture2 - pieChart - piggyBank - pilcrow - pilcrowSquare - pill - pin - pinOff - pipette - pizza - plane - play - playCircle - playSquare - plug - plug2 - plugZap - plus - plusCircle - plusSquare - podcast - pointer - poundSterling - power - powerOff - printer - puzzle - qrCode - quote - radio - radioReceiver - radioTower - rat - receipt - rectangleHorizontal - rectangleVertical - recycle - redo - redo2 - refreshCcw - refreshCw - refrigerator - regex - removeFormatting - repeat - repeat1 - replace - replaceAll - reply - replyAll - rewind - rocket - rockingChair - rotate3d - rotateCcw - rotateCw - rss - ruler - russianRuble - sailboat - salad - save - scale - scale3d - scaling - scan - scanFace - scanLine - scissors - screenShare - screenShareOff - scroll - scrollText - search - searchSlash - searchX - send - separatorHorizontal - separatorVertical - server - serverCog - serverCrash - serverOff - settings - settings2 - share - share2 - sheet - shield - shieldAlert - shieldCheck - shieldClose - shieldOff - shieldQuestion - ship - shirt - shoppingBag - shoppingCart - shovel - showerHead - shrink - shrub - shuffle - sidebar - sidebarClose - sidebarOpen - sigma - sigmaSquare - signal - signalHigh - signalLow - signalMedium - signalZero - skipBack - skipForward - skull - slack - slash - slice - sliders - slidersHorizontal - smartphone - smile - snowflake - sofa - sortAsc - sortDesc - soup - speaker - spline - split - splitSquareHorizontal - splitSquareVertical - sprout - square - squareAsterisk - squareDot - squareEqual - squareSlash - stamp - star - starOff - stepBack - stepForward - stethoscope - sticker - stickyNote - stopCircle - store - stretchHorizontal - stretchVertical - strikethrough - subscript - sun - sunDim - sunMedium - sunMoon - sunSnow - sunrise - sunset - superscript - swissFranc - switchCamera - sword - swords - syringe - table - table2 - tableProperties - tablet - tablets - tag - tags - target - tent - terminal - terminalSquare - testTube - testTube2 - textCursor - textCursorInput - textQuote - textSelect - thermometer - thermometerSnowflake - thermometerSun - thumbsDown - thumbsUp - ticket - timer - timerOff - timerReset - toggleLeft - toggleRight - tornado - toyBrick - train - trash - trash2 - treeDeciduous - treePine - trees - trendingDown - trendingUp - triangle - trophy - truck - tv - tv2 - type - umbrella - underline - undo - undo2 - unlink - unlink2 - unlock - unlockKeyhole - upload - uploadCloud - usb - user - userCheck - userCog - userMinus - userPlus - userX - users - utensils - utensilsCrossed - verified - vibrate - vibrateOff - video - videoOff - view - voicemail - volume - volume1 - volume2 - volumeX - vote - wallet - wallet2 - watch - waves - webcam - webhook - wifi - wifiOff - wind - wine - wineOff - wrapText - wrench - x - xCircle - xOctagon - xSquare - zap - zapOff - zoomIn - zoomOut description: >- Icon identifier for the widget launcher button. Optional. Default: `"phone"`. Must be one of the supported Lucide icon names listed in the enum. default: phone example: phone position: type: string enum: - bottom-right - bottom-left - top-right - top-left description: >- Widget position on the page. Optional. Default: `"bottom-right"`. Valid values: `"bottom-right"`, `"bottom-left"`, `"top-right"`, `"top-left"`. default: bottom-right example: bottom-right borderRadius: type: string enum: - none - small - medium - large description: >- Border radius of the widget. Optional. Default: `"medium"`. Valid values: `"none"`, `"small"`, `"medium"`, `"large"`. default: medium example: medium ctaBorderRadius: type: string enum: - none - small - medium - large - full description: >- Border radius of the CTA button. Optional. Default: `"medium"`. Valid values: `"none"`, `"small"`, `"medium"`, `"large"`, `"full"`. default: medium example: medium size: type: string enum: - tiny - compact - large description: >- Widget size. Optional. Default: `"compact"`. Valid values: `"tiny"`, `"compact"`, `"large"`. default: compact example: compact title: type: string description: 'Widget title text. Optional. Default: `"AI Assistant"`.' default: AI Assistant example: AI Assistant subtitle: type: string description: >- Widget subtitle text shown below the title. Optional. Default: `"Get instant help from our AI"`. default: Get instant help from our AI example: Get instant help from our AI ctaButtonText: type: string description: >- Text displayed on the CTA button. Optional. Default: `"Start Conversation"`. default: Start Conversation example: Start Conversation chatPlaceholder: type: string description: >- Placeholder text for the chat input field. Optional. Default: `"Type your message..."`. default: Type your message... example: Type your message... chatFirstMessage: type: string description: >- First message shown in the chat window when a conversation starts. Optional. Default: `"Hello! How can I help you today?"`. default: Hello! How can I help you today? example: Hello! How can I help you today? chatConnectedText: type: string description: >- Text shown when the chat session is connected. Optional. Default: `"Connected"`. default: Connected example: Connected chatEndButtonText: type: string description: 'Text on the chat end button. Optional. Default: `"End"`.' default: End example: End chatStartingText: type: string description: >- Text shown while the chat session is initialising. Optional. Default: `"Starting conversation..."`. default: Starting conversation... example: Starting conversation... chatConnectingText: type: string description: >- Text shown while the chat is connecting. Optional. Default: `"Connecting..."`. default: Connecting... example: Connecting... chatStartConversationText: type: string description: >- Prompt text to start a chat conversation. Optional. Default: `"Start a conversation"`. default: Start a conversation example: Start a conversation chatTypeToStartText: type: string description: >- Helper text shown before the user types the first message. Optional. Default: `"Type a message to start chatting"`. default: Type a message to start chatting example: Type a message to start chatting chatInactivityTimeoutMinutes: type: integer minimum: 1 maximum: 60 description: >- Minutes of inactivity before the chat session ends automatically. Optional. Default: `3`. Range: 1–60. default: 3 example: 3 modeSelectionText: type: string description: >- Prompt text shown when both voice and chat modes are enabled and the user must choose. Optional. Default: `"How would you like to interact?"`. default: How would you like to interact? example: How would you like to interact? voiceStartButtonText: type: string description: >- Text on the voice start button. Optional. Default: `"Start Voice Call"`. default: Start Voice Call example: Start Voice Call voiceEndButtonText: type: string description: >- Text on the voice end/hang-up button. Optional. Default: `"End Call"`. default: End Call example: End Call permissionDeniedMessage: type: string description: >- Message shown when the user denies microphone permission. Optional. example: Microphone access is required for voice calls. permissionPromptMessage: type: string description: Message shown when requesting microphone permission. Optional. example: Please allow microphone access to start a voice call. footerText: type: string description: Footer text displayed at the bottom of the widget. Optional. example: Powered by VoiceAI enableConsent: type: boolean description: >- When true, shows a consent/privacy popup before the user can interact. Optional. Default: `true`. default: true example: true consentTitle: type: string description: >- Title of the consent popup. Optional. Default: `"Privacy Notice"`. default: Privacy Notice example: Privacy Notice consentText: type: string description: >- Body text of the consent popup. Optional. Defaults to a standard privacy notice. example: >- By continuing, you agree to our privacy policy and terms of service. consentAcceptButtonText: type: string description: >- Text on the consent accept button. Optional. Default: `"Accept"`. default: Accept example: Accept consentCancelButtonText: type: string description: >- Text on the consent cancel/decline button. Optional. Default: `"Cancel"`. default: Cancel example: Cancel localStorageKey: type: string description: >- LocalStorage key used to persist the user's consent decision. Optional. Default: `"ai-widget-consent"`. default: ai-widget-consent example: ai-widget-consent example: mode: - voice theme: light position: bottom-right title: AI Assistant subtitle: Get instant help from our AI ctaButtonText: Start Conversation accentColor: '#3b82f6' ctaButtonColor: '#3b82f6' ErrorWithList: type: object properties: message: type: string errors: type: array items: type: string ErrorMessage: type: object properties: message: type: string securitySchemes: bearerAuth: type: http scheme: bearer ````