vCita Web AI Widget API

Widget configuration resources under `/v3/online_presence/widget_configurations`.

GitHub OpenAPI

Operations 5

GET /v3/online_presence/widget_configurations Get all WidgetConfigurations #
POST /v3/online_presence/widget_configurations Create a WidgetConfigurations #
GET /v3/online_presence/widget_configurations/{uid} Retrieve a WidgetConfigurations #
PUT /v3/online_presence/widget_configurations/{uid} Update WidgetConfigurations #
DELETE /v3/online_presence/widget_configurations/{uid} Delete a WidgetConfigurations #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/vcita:vcita-web-ai-widget-api"
All apis
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.

Get an API 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 Specification

vcita-web-ai-widget-api-openapi.yml Raw ↑
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