vCita Web AI Widget API
Widget configuration resources under `/v3/online_presence/widget_configurations`.
Widget configuration resources under `/v3/online_presence/widget_configurations`.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/vcita:vcita-web-ai-widget-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Online_presence Web AI Widget API
description: Unified OpenAPI specification for online_presence domain
version: '3.0'
x-generated:
sourceFiles:
- widget_configurations.json
- ai_chat_configurations.json
- ai_receptionist_conversations.json
pathNormalizations: []
pathConflicts: []
componentConflicts:
- type: schema
name: ErrorResponse
resolution: Renamed to ErrorResponse_ai_chat_configurations
files:
- merged
- ai_chat_configurations.json
- type: schema
name: NestHttpException
resolution: Renamed to NestHttpException_ai_receptionist_conversations
files:
- merged
- ai_receptionist_conversations.json
totalPaths: 5
totalComponents: 17
servers:
- url: https://api.vcita.biz
description: Unified API Gateway server
tags:
- name: Web AI Widget
description: Widget configuration resources under `/v3/online_presence/widget_configurations`.
paths:
/v3/online_presence/widget_configurations:
get:
operationId: listWidgetConfigurations
summary: Get all WidgetConfigurations
description: Lists widget configurations. Available for **Staff tokens**
tags:
- Web AI Widget
parameters:
- name: page
in: query
required: false
description: 1-based page index
schema:
type: integer
minimum: 1
default: 1
- name: per_page
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 25
- name: sort
in: query
required: false
description: e.g. `created_at:desc` or `updated_at:asc`. Direction defaults to `asc` if omitted.
schema:
type: string
example: created_at:desc
responses:
'200':
description: List result
content:
application/json:
schema:
allOf:
- type: object
properties:
success:
type: boolean
description: Indicates whether the API request was successful (true) or failed (false).
data:
type: object
description: 'The response payload. Present on successful responses (success: true).'
error:
type: string
description: Error message for simple error responses. Used in some legacy endpoints.
errors:
type: array
description: 'Array of error objects for detailed error responses. Present on error responses (success: false).'
items:
type: object
properties:
code:
type: string
description: Machine-readable error code (e.g., 'already_exists', 'invalid', 'not_found').
message:
type: string
description: Human-readable error message.
field:
type: string
description: The field that caused the error (for validation errors).
required:
- code
- message
required:
- success
description: Generic wrapper object for API responses. Success responses contain 'data', while error responses contain 'errors' array or 'error' string.
- type: object
properties:
data:
$ref: '#/components/schemas/ListWidgetConfigurationsPayload'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/NestHttpException'
'403':
description: Forbidden — business mismatch
content:
application/json:
schema:
$ref: '#/components/schemas/NestHttpException'
'404':
description: Not found (masked as 404 for business mismatch in some cases)
content:
application/json:
schema:
$ref: '#/components/schemas/NestHttpException'
'422':
description: Semantic validation or bad query (e.g. legacy sort params)
content:
application/json:
schema:
$ref: '#/components/schemas/NestHttpException'
example:
success: false
errors:
- field: sort
code: invalid
message: 'sort field must be one of: created_at, updated_at, business_uid'
security:
- WidgetConfigurations: []
post:
operationId: createWidgetConfiguration
summary: Create a WidgetConfigurations
description: Creates a widget configuration for a business. Available for **Staff token**;
tags:
- Web AI Widget
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RequestCreateWidgetConfiguration'
responses:
'201':
description: Created
content:
application/json:
schema:
allOf:
- type: object
properties:
success:
type: boolean
description: Indicates whether the API request was successful (true) or failed (false).
data:
type: object
description: 'The response payload. Present on successful responses (success: true).'
error:
type: string
description: Error message for simple error responses. Used in some legacy endpoints.
errors:
type: array
description: 'Array of error objects for detailed error responses. Present on error responses (success: false).'
items:
type: object
properties:
code:
type: string
description: Machine-readable error code (e.g., 'already_exists', 'invalid', 'not_found').
message:
type: string
description: Human-readable error message.
field:
type: string
description: The field that caused the error (for validation errors).
required:
- code
- message
required:
- success
description: Generic wrapper object for API responses. Success responses contain 'data', while error responses contain 'errors' array or 'error' string.
- type: object
properties:
data:
$ref: '#/components/schemas/WidgetConfigurationResource'
'400':
description: Malformed request syntax (e.g., invalid JSON payload)
content:
application/json:
schema:
$ref: '#/components/schemas/NestHttpException'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/NestHttpException'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/NestHttpException'
'422':
description: Semantic validation or business-rule failure
content:
application/json:
schema:
$ref: '#/components/schemas/NestHttpException'
security:
- WidgetConfigurations: []
/v3/online_presence/widget_configurations/{uid}:
get:
operationId: getWidgetConfigurationByUid
summary: Retrieve a WidgetConfigurations
description: Returns one widget configuration. Available for **Staff token**
tags:
- Web AI Widget
parameters:
- name: uid
in: path
required: true
schema:
type: string
responses:
'200':
description: Configuration
content:
application/json:
schema:
allOf:
- type: object
properties:
success:
type: boolean
description: Indicates whether the API request was successful (true) or failed (false).
data:
type: object
description: 'The response payload. Present on successful responses (success: true).'
error:
type: string
description: Error message for simple error responses. Used in some legacy endpoints.
errors:
type: array
description: 'Array of error objects for detailed error responses. Present on error responses (success: false).'
items:
type: object
properties:
code:
type: string
description: Machine-readable error code (e.g., 'already_exists', 'invalid', 'not_found').
message:
type: string
description: Human-readable error message.
field:
type: string
description: The field that caused the error (for validation errors).
required:
- code
- message
required:
- success
description: Generic wrapper object for API responses. Success responses contain 'data', while error responses contain 'errors' array or 'error' string.
- type: object
properties:
data:
$ref: '#/components/schemas/WidgetConfigurationResource'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/NestHttpException'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/NestHttpException'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/NestHttpException'
security:
- WidgetConfigurations: []
put:
operationId: updateWidgetConfiguration
summary: Update WidgetConfigurations
description: Updates an existing widget configuration. Available fo **Staff token**
tags:
- Web AI Widget
parameters:
- name: uid
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RequestUpdateWidgetConfiguration'
responses:
'200':
description: Updated configuration
content:
application/json:
schema:
allOf:
- type: object
properties:
success:
type: boolean
description: Indicates whether the API request was successful (true) or failed (false).
data:
type: object
description: 'The response payload. Present on successful responses (success: true).'
error:
type: string
description: Error message for simple error responses. Used in some legacy endpoints.
errors:
type: array
description: 'Array of error objects for detailed error responses. Present on error responses (success: false).'
items:
type: object
properties:
code:
type: string
description: Machine-readable error code (e.g., 'already_exists', 'invalid', 'not_found').
message:
type: string
description: Human-readable error message.
field:
type: string
description: The field that caused the error (for validation errors).
required:
- code
- message
required:
- success
description: Generic wrapper object for API responses. Success responses contain 'data', while error responses contain 'errors' array or 'error' string.
- type: object
properties:
data:
$ref: '#/components/schemas/WidgetConfigurationResource'
'400':
description: Malformed request syntax (e.g., invalid JSON payload)
content:
application/json:
schema:
$ref: '#/components/schemas/NestHttpException'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/NestHttpException'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/NestHttpException'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/NestHttpException'
'422':
description: Semantic validation or business-rule failure
content:
application/json:
schema:
$ref: '#/components/schemas/NestHttpException'
security:
- WidgetConfigurations: []
delete:
operationId: deleteWidgetConfiguration
summary: Delete a WidgetConfigurations
description: Deletes a widget configuration. Available for **Staff token**
tags:
- Web AI Widget
parameters:
- name: uid
in: path
required: true
schema:
type: string
responses:
'200':
description: 'The deleted widget configuration (`{ success: true, data }`)'
content:
application/json:
schema:
allOf:
- type: object
properties:
success:
type: boolean
description: Indicates whether the API request was successful (true) or failed (false).
data:
type: object
description: 'The response payload. Present on successful responses (success: true).'
error:
type: string
description: Error message for simple error responses. Used in some legacy endpoints.
errors:
type: array
description: 'Array of error objects for detailed error responses. Present on error responses (success: false).'
items:
type: object
properties:
code:
type: string
description: Machine-readable error code (e.g., 'already_exists', 'invalid', 'not_found').
message:
type: string
description: Human-readable error message.
field:
type: string
description: The field that caused the error (for validation errors).
required:
- code
- message
required:
- success
description: Generic wrapper object for API responses. Success responses contain 'data', while error responses contain 'errors' array or 'error' string.
- type: object
properties:
data:
$ref: '#/components/schemas/WidgetConfigurationResource'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/NestHttpException'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/NestHttpException'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/NestHttpException'
security:
- WidgetConfigurations: []
components:
schemas:
RequestCreateWidgetConfiguration:
type: object
properties:
widget_title:
type: string
nullable: true
maxLength: 200
description: Widget title shown in the chat header.
welcome_message:
type: string
nullable: true
maxLength: 1000
description: Message shown when the widget chat opens.
brand_color:
type: string
nullable: true
description: Hex color
text_color:
type: string
nullable: true
description: Hex color
logo_url:
type: string
nullable: true
format: uri
description: Public logo URL shown in the widget.
actions:
type: array
nullable: true
description: Ordered list of configured portal actions.
items:
$ref: '#/components/schemas/ActionConfigItem'
auto_popup_enabled:
type: boolean
nullable: true
description: Whether the widget auto-opens for visitors.
auto_popup_delay:
type: number
nullable: true
minimum: 0
maximum: 3600
description: Auto-open delay in seconds.
welcome_buttons:
type: array
nullable: true
description: Quick-reply buttons shown under the welcome message.
items:
$ref: '#/components/schemas/WelcomeButton'
button_text:
type: string
nullable: true
maxLength: 200
description: Launcher button label shown before opening the widget.
ai_receptionist_enabled:
type: boolean
nullable: true
description: Whether the AI Receptionist answers chats in the website widget (the Web channel). **false** makes the widget open with the welcome message, the actions and a "Leave a message" button, without AI. Other channels are not affected. **true** or null runs the AI while the AI Receptionist is enabled and AI chats are left this month. Null means true (e.g., true, false or null).
ActionConfigItem:
type: object
description: A single client-portal action in the stored widget configuration. Order follows array position in the API.
properties:
uid:
type: string
nullable: true
description: Portal action UID. Required by the API for persisted actions; nullable only for legacy/backfill reads.
action:
type: string
description: Action key/type (client-portal action identifier).
label:
type: string
nullable: true
maxLength: 200
description: Display label override; omit or null to resolve from portal defaults.
availability:
type: boolean
description: Whether this action is available in the widget.
required:
- uid
- action
- availability
NestHttpException:
type: object
description: Standard v3 error envelope.
properties:
success:
type: boolean
description: Always false for error responses.
enum:
- false
errors:
type: array
description: List of error details describing what failed.
items:
type: object
properties:
field:
type: string
nullable: true
description: Request field that failed validation, when applicable.
code:
type: string
description: Machine-readable error code.
message:
type: string
description: Human-readable error message.
required:
- code
- message
required:
- success
- errors
ListWidgetConfigurationsPayload:
type: object
properties:
widget_configurations:
type: array
description: Widget configurations for the authenticated business on the current page.
items:
$ref: '#/components/schemas/WidgetConfigurationResource'
total:
type: integer
minimum: 0
description: Total number of widget configurations across all pages.
required:
- widget_configurations
- total
RequestUpdateWidgetConfiguration:
type: object
description: Partial update request. All fields are optional.
properties:
widget_title:
type: string
nullable: true
maxLength: 200
description: Widget title shown in the chat header.
welcome_message:
type: string
nullable: true
maxLength: 1000
description: Message shown when the widget chat opens.
brand_color:
type: string
nullable: true
description: Widget brand color in hex format.
text_color:
type: string
nullable: true
description: Widget text color in hex format.
logo_url:
type: string
nullable: true
format: uri
description: Public logo URL shown in the widget.
actions:
type: array
nullable: true
description: Ordered list of configured portal actions.
items:
$ref: '#/components/schemas/ActionConfigItem'
auto_popup_enabled:
type: boolean
nullable: true
description: Whether the widget auto-opens for visitors.
auto_popup_delay:
type: number
nullable: true
minimum: 0
maximum: 3600
description: Auto-open delay in seconds.
welcome_buttons:
type: array
nullable: true
description: Quick-reply buttons shown under the welcome message.
items:
$ref: '#/components/schemas/WelcomeButton'
button_text:
type: string
nullable: true
maxLength: 200
description: Launcher button label shown before opening the widget.
ai_receptionist_enabled:
type: boolean
nullable: true
description: Whether the AI Receptionist answers chats in the website widget (the Web channel). **false** makes the widget open with the welcome message, the actions and a "Leave a message" button, without AI. Other channels are not affected. **true** or null runs the AI while the AI Receptionist is enabled and AI chats are left this month. Null means true (e.g., true, false or null).
WelcomeButton:
type: object
description: Quick-reply button shown under the welcome message in the Web AI Widget.
properties:
label:
type: string
description: Button label shown to the visitor.
message:
type: string
description: Message text sent to the assistant when the button is clicked.
required:
- label
- message
WidgetConfigurationResource:
type: object
description: 'The Web AI Widget configuration for a business — controls the embedded chat widget''s appearance, welcome message, quick-reply buttons, and client-portal actions. Sparse: any field you omit falls back to the product default. Returned directly under `data` (wrapped by the standard response envelope) by the widget configuration APIs.'
properties:
uid:
type: string
readOnly: true
description: Configuration row UID.
business_uid:
type: string
description: Owning business UID.
created_at:
type: string
format: date-time
readOnly: true
description: Row creation time (ISO 8601).
updated_at:
type: string
format: date-time
readOnly: true
description: Last update time (ISO 8601).
owner_uid:
type: string
nullable: true
description: Staff UID of the last editor (widget editor saves).
widget_title:
type: string
description: Header title shown in the widget.
welcome_message:
type: string
description: Opening message when chat starts.
brand_color:
type: string
description: Brand/theme color (hex).
text_color:
type: string
description: Text color (hex).
logo_url:
type: string
nullable: true
format: uri
description: Logo image URL.
actions:
type: array
description: Structured portal actions; order = array order.
items:
type: object
description: A single client-portal action in the stored widget configuration. Order follows array position in the API.
properties:
uid:
type: string
nullable: true
description: Portal action UID. Required by the API for persisted actions; nullable only for legacy/backfill reads.
action:
type: string
description: Action key/type (client-portal action identifier).
label:
type: string
nullable: true
maxLength: 200
description: Display label override; omit or null to resolve from portal defaults.
availability:
type: boolean
description: Whether this action is available in the widget.
required:
- uid
- action
- availability
auto_popup_enabled:
type: boolean
description: Whether the widget auto-opens.
auto_popup_delay:
type: number
description: Delay before auto-popup (seconds, 0–3600).
welcome_buttons:
type: array
items:
type: object
description: Quick-reply button shown under the welcome message in the Web AI Widget.
properties:
label:
type: string
description: Button label shown to the visitor.
message:
type: string
description: Message text sent to the assistant when the button is clicked.
required:
- label
- message
button_text:
type: string
description: Engage / launcher button label.
ai_receptionist_enabled:
type: boolean
nullable: true
description: Whether the AI Receptionist answers chats in the website widget (the Web channel). **false** makes the widget open with the welcome message, the actions and a "Leave a message" button, without AI. Other channels are not affected. **true** or null runs the AI while the AI Receptionist is enabled and AI chats are left this month. Null means true (e.g., true, false or null).
website_widget_detected:
type: boolean
nullable: true
readOnly: true
description: Whether the widget has loaded on a website at least once. Loads in the widget editor and the widget preview do not count. Set by the server only. The AI Receptionist uses it to tell whether the new widget is on the website (e.g., true, false or null).
example:
uid: widcfg_48b3f7a2
business_uid: biz_2f8f7ab1
created_at: '2026-04-22T10:30:00.000Z'
updated_at: '2026-04-22T11:12:45.000Z'
owner_uid: staff_1182abc
widget_title: Acme Plumbing AI Assistant
welcome_message: Hi! Need help with plumbing services?
brand_color: '#1f7ae0'
text_color: '#ffffff'
logo_url: https://cdn.example.com/acme/logo.png
actions:
- uid: action_book
action: book_appointment
label: Book now
availability: true
- uid: action_call
action: call_business
label: Call us
availability: true
auto_popup_enabled: true
auto_popup_delay: 8
welcome_buttons:
- label: Book an appointment
message: I want to book an appointment.
- label: Emergency service
message: Do you provide emergency plumbing service?
button_text: Chat with us
ai_receptionist_enabled: true
website_widget_detected: true
securitySchemes:
WidgetConfigurations:
type: http
scheme: bearer
bearerFormat: JWT
description: Business token (and optional Staff token where the API supports attribution). The business is derived from the authenticated token.
Bearer:
type: http
scheme: bearer
bearerFormat: JWT
description: 'Provide a valid bearer token in the Authorization header. Example: ''Authorization: Bearer {app_token}'''
AiReceptionistConversations:
type: http
scheme: bearer
bearerFormat: JWT
description: '**Staff tokens** — business context is taken from the token for conversations.'
x-provenance:
method: searched
source: https://developers.intandem.tech:443/reference
harvested: '2026-11-15'
tool: harvest-readme-openapi.py
note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
assembled_from:
- https://developers.intandem.tech/reference/createaireceptionistconversation.md
- https://developers.intandem.tech/reference/createwidgetconfiguration.md
- https://developers.intandem.tech/reference/deleteaireceptionistconversation.md
- https://developers.intandem.tech/reference/deletewidgetconfiguration.md
- https://developers.intandem.tech/reference/getaichatconfiguration.md
- https://developers.intandem.tech/reference/getaireceptionistconversation.md
- https://developers.intandem.tech/reference/getwidgetconfigurationbyuid.md
- https://developers.intandem.tech/reference/listaireceptionistconversations.md
- https://developers.intandem.tech/reference/listwidgetconfigurations.md
- https://developers.intandem.tech/reference/updateaireceptionistconversation.md
- https://developers.intandem.tech/reference/updatewidgetconfiguration.md
- https://developers.intandem.tech/reference/upsertaichatconfiguration.md
- https://developers.intandem.tech:443/reference/createaireceptionistconversation.md
- https://developers.intandem.tech:443/reference/createwidgetconfiguration.md
- https://developers.intandem.tech:443/reference/deleteaireceptionistconversation.md
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://artifacts.apis.io/vcita/openapi/vcita-web-ai-widget-api-openapi.yml