vCita AI Chat Configuration API

AI chat behavior configuration for the authenticated business (**Staff tokens**).

GitHub OpenAPI

Operations 2

GET /v3/online_presence/ai_chat_configurations Retrieve an AIChatConfiguration #
PUT /v3/online_presence/ai_chat_configurations Update an AIChatConfiguration #

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-ai-chat-configuration-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-ai-chat-configuration-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Online_presence AI Chat Configuration 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: AI Chat Configuration
  description: AI chat behavior configuration for the authenticated business (**Staff tokens**).
paths:
  /v3/online_presence/ai_chat_configurations:
    get:
      tags:
      - AI Chat Configuration
      summary: Retrieve an AIChatConfiguration
      description: Returns the AI chat configuration for the authenticated business. Available for **Staff tokens**.
      operationId: getAiChatConfiguration
      responses:
        '200':
          description: AI chat configuration retrieved successfully.
          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.
                - properties:
                    data:
                      type: object
                      description: 'AI Receptionist Configuration for a business: controls how the AI receptionist behaves across all channels (web widget, WhatsApp, etc.). Includes FAQ/guidance, lead capture settings, business hours, knowledge inclusion flags, and proactive action offers. Returned inside `data` (wrapped by standard Response) for authenticated CRUD/main APIs.'
                      properties:
                        uid:
                          type: string
                          readOnly: true
                          description: Configuration row UID.
                        business_uid:
                          type: string
                          readOnly: true
                          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
                          readOnly: true
                          description: Staff UID of the last editor.
                        config:
                          type: object
                          description: The AI chat configuration blob. Sparse — omitted keys use product defaults.
                          properties:
                            business_hours:
                              type: string
                              nullable: true
                              description: Business hours text; null uses calendar-derived defaults.
                            lead_basic_contact_fields:
                              type: string
                              nullable: true
                              enum:
                              - phone_or_email
                              - phone
                              - email
                              - both
                              description: Contact info the AI receptionist must try to collect before creating a lead. Guidance only; the CRM still creates a lead whenever a name and at least one of phone/email are present. Null uses the default (e.g., "phone_or_email").
                            lead_fields:
                              type: array
                              nullable: true
                              description: Additional lead fields the AI receptionist should try to collect (optional, never blocking).
                              maxItems: 10
                              items:
                                type: object
                                properties:
                                  label:
                                    type: string
                                    nullable: true
                                    maxLength: 100
                                    description: Field label (e.g., "Address", "Preferred time").
                                  instructions:
                                    type: string
                                    nullable: true
                                    maxLength: 200
                                    description: When/why to ask for this field (e.g., "Only ask if the customer is requesting a home visit.").
                            include_contact_info:
                              type: boolean
                              nullable: true
                              description: Whether to include business contact info in AI guidance context.
                            include_services:
                              type: boolean
                              nullable: true
                              description: Whether to include business services in AI guidance context.
                            include_products:
                              type: boolean
                              nullable: true
                              description: Whether to include business products in AI guidance context.
                            include_booking_policies:
                              type: boolean
                              nullable: true
                              description: Whether to include booking policies in AI guidance context.
                            include_terms_of_service:
                              type: boolean
                              nullable: true
                              description: Whether to include terms of service in AI guidance context.
                            guidance_urls:
                              type: array
                              nullable: true
                              items:
                                type: string
                                format: uri
                              description: Extra URLs whose content is merged into AI guidance.
                            ai_actions:
                              type: array
                              nullable: true
                              description: AI proactive action behavior. Defines which actions the AI should proactively offer and when.
                              items:
                                type: object
                                properties:
                                  action_uid:
                                    type: string
                                    description: Portal action UID.
                                  action_key:
                                    type: string
                                    description: Action key/type (e.g., "schedule", "contact").
                                  should_offer:
                                    type: boolean
                                    description: Whether the AI should proactively suggest this action.
                                  when_to_offer:
                                    type: string
                                    nullable: true
                                    maxLength: 200
                                    description: Guidance text for when the AI should suggest this action (e.g., "Offer when client asks about scheduling").
                                required:
                                - action_uid
                                - action_key
                                - should_offer
                            receptionist_enabled:
                              type: boolean
                              nullable: true
                              default: true
                              description: 'Whether the AI Receptionist is enabled. **false** turns the AI off for new conversations: website visitors can leave a message, messages from messaging apps go to the inbox, and calls go to voicemail. **true** or null runs the AI until the monthly AI chat quota is used up. Defaults to true. A business with no AiReceptionistConfiguration at all (GET returns 404) has the AI Receptionist off until a configuration is saved (e.g., true, false or null).'
                      example:
                        uid: aicfg_7c2d4e91
                        business_uid: biz_2f8f7ab1
                        created_at: '2026-05-28T10:30:00.000Z'
                        updated_at: '2026-05-28T11:12:45.000Z'
                        owner_uid: staff_1182abc
                        config:
                          business_hours: Mon-Fri 08:00-18:00, Sat 09:00-14:00
                          lead_basic_contact_fields: phone_or_email
                          lead_fields:
                          - label: Address
                            instructions: Only ask if the customer is requesting a home visit.
                          include_contact_info: true
                          include_services: true
                          include_products: false
                          include_booking_policies: true
                          include_terms_of_service: false
                          guidance_urls:
                          - https://example.com/faq
                          receptionist_enabled: true
                          ai_actions:
                          - action_uid: action_book
                            action_key: schedule
                            should_offer: true
                            when_to_offer: Offer when client asks about scheduling or availability.
                          - action_uid: action_call
                            action_key: contact
                            should_offer: false
                            when_to_offer: null
        '401':
          description: Unauthorized — missing or invalid token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found — no AI chat configuration exists for this business yet. Until one is saved, the AI Receptionist is off on every channel.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                errors:
                - code: not_found
                  message: AI chat configuration not found for this business
      security:
      - Bearer: []
    put:
      tags:
      - AI Chat Configuration
      summary: Update an AIChatConfiguration
      description: Creates or updates the AI chat configuration for the authenticated business. Provided fields are merged with existing values; omitted fields are unchanged. Available for **Staff tokens**.
      operationId: upsertAiChatConfiguration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertAiChatConfigRequest'
            examples:
              turn_off_ai:
                summary: Turn the AI Receptionist off
                description: New conversations run without AI. Other settings are unchanged.
                value:
                  receptionist_enabled: false
              turn_on_ai:
                summary: Turn the AI Receptionist on
                description: New conversations run the AI until the monthly AI chat quota is used up.
                value:
                  receptionist_enabled: true
      responses:
        '200':
          description: AI chat configuration updated successfully.
          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.
                - properties:
                    data:
                      type: object
                      description: 'AI Receptionist Configuration for a business: controls how the AI receptionist behaves across all channels (web widget, WhatsApp, etc.). Includes FAQ/guidance, lead capture settings, business hours, knowledge inclusion flags, and proactive action offers. Returned inside `data` (wrapped by standard Response) for authenticated CRUD/main APIs.'
                      properties:
                        uid:
                          type: string
                          readOnly: true
                          description: Configuration row UID.
                        business_uid:
                          type: string
                          readOnly: true
                          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
                          readOnly: true
                          description: Staff UID of the last editor.
                        config:
                          type: object
                          description: The AI chat configuration blob. Sparse — omitted keys use product defaults.
                          properties:
                            business_hours:
                              type: string
                              nullable: true
                              description: Business hours text; null uses calendar-derived defaults.
                            lead_basic_contact_fields:
                              type: string
                              nullable: true
                              enum:
                              - phone_or_email
                              - phone
                              - email
                              - both
                              description: Contact info the AI receptionist must try to collect before creating a lead. Guidance only; the CRM still creates a lead whenever a name and at least one of phone/email are present. Null uses the default (e.g., "phone_or_email").
                            lead_fields:
                              type: array
                              nullable: true
                              description: Additional lead fields the AI receptionist should try to collect (optional, never blocking).
                              maxItems: 10
                              items:
                                type: object
                                properties:
                                  label:
                                    type: string
                                    nullable: true
                                    maxLength: 100
                                    description: Field label (e.g., "Address", "Preferred time").
                                  instructions:
                                    type: string
                                    nullable: true
                                    maxLength: 200
                                    description: When/why to ask for this field (e.g., "Only ask if the customer is requesting a home visit.").
                            include_contact_info:
                              type: boolean
                              nullable: true
                              description: Whether to include business contact info in AI guidance context.
                            include_services:
                              type: boolean
                              nullable: true
                              description: Whether to include business services in AI guidance context.
                            include_products:
                              type: boolean
                              nullable: true
                              description: Whether to include business products in AI guidance context.
                            include_booking_policies:
                              type: boolean
                              nullable: true
                              description: Whether to include booking policies in AI guidance context.
                            include_terms_of_service:
                              type: boolean
                              nullable: true
                              description: Whether to include terms of service in AI guidance context.
                            guidance_urls:
                              type: array
                              nullable: true
                              items:
                                type: string
                                format: uri
                              description: Extra URLs whose content is merged into AI guidance.
                            ai_actions:
                              type: array
                              nullable: true
                              description: AI proactive action behavior. Defines which actions the AI should proactively offer and when.
                              items:
                                type: object
                                properties:
                                  action_uid:
                                    type: string
                                    description: Portal action UID.
                                  action_key:
                                    type: string
                                    description: Action key/type (e.g., "schedule", "contact").
                                  should_offer:
                                    type: boolean
                                    description: Whether the AI should proactively suggest this action.
                                  when_to_offer:
                                    type: string
                                    nullable: true
                                    maxLength: 200
                                    description: Guidance text for when the AI should suggest this action (e.g., "Offer when client asks about scheduling").
                                required:
                                - action_uid
                                - action_key
                                - should_offer
                            receptionist_enabled:
                              type: boolean
                              nullable: true
                              default: true
                              description: 'Whether the AI Receptionist is enabled. **false** turns the AI off for new conversations: website visitors can leave a message, messages from messaging apps go to the inbox, and calls go to voicemail. **true** or null runs the AI until the monthly AI chat quota is used up. Defaults to true. A business with no AiReceptionistConfiguration at all (GET returns 404) has the AI Receptionist off until a configuration is saved (e.g., true, false or null).'
                      example:
                        uid: aicfg_7c2d4e91
                        business_uid: biz_2f8f7ab1
                        created_at: '2026-05-28T10:30:00.000Z'
                        updated_at: '2026-05-28T11:12:45.000Z'
                        owner_uid: staff_1182abc
                        config:
                          business_hours: Mon-Fri 08:00-18:00, Sat 09:00-14:00
                          lead_basic_contact_fields: phone_or_email
                          lead_fields:
                          - label: Address
                            instructions: Only ask if the customer is requesting a home visit.
                          include_contact_info: true
                          include_services: true
                          include_products: false
                          include_booking_policies: true
                          include_terms_of_service: false
                          guidance_urls:
                          - https://example.com/faq
                          receptionist_enabled: true
                          ai_actions:
                          - action_uid: action_book
                            action_key: schedule
                            should_offer: true
                            when_to_offer: Offer when client asks about scheduling or availability.
                          - action_uid: action_call
                            action_key: contact
                            should_offer: false
                            when_to_offer: null
        '401':
          description: Unauthorized — missing or invalid token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity — validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                errors:
                - code: invalid
                  field: ai_actions
                  message: ai_actions must be an array
      security:
      - Bearer: []
components:
  schemas:
    ErrorResponse:
      type: object
      description: Standard v3 error envelope.
      properties:
        success:
          type: boolean
          description: Always false for error responses.
        errors:
          type: array
          description: List of error details describing what failed.
          items:
            type: object
            properties:
              field:
                type: string
                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:
      - success
      - errors
    UpsertAiChatConfigRequest:
      type: object
      description: Request body for upserting the AI chat configuration. All fields are optional — only provided fields are merged with existing values.
      properties:
        business_hours:
          type: string
          nullable: true
          description: Business hours text; null uses calendar-derived defaults.
        lead_basic_contact_fields:
          type: string
          nullable: true
          enum:
          - phone_or_email
          - phone
          - email
          - both
          description: Contact info the AI receptionist must try to collect before creating a lead. Guidance only; the CRM still creates a lead whenever a name and at least one of phone/email are present. Null uses the default (e.g., "phone_or_email").
        lead_fields:
          type: array
          nullable: true
          maxItems: 10
          description: Additional lead fields the AI receptionist should try to collect (optional, never blocking).
          items:
            type: object
            properties:
              label:
                type: string
                nullable: true
                maxLength: 100
                description: Field label (e.g., "Address").
              instructions:
                type: string
                nullable: true
                maxLength: 200
                description: When/why to ask for this field (e.g., "Only ask if the customer is requesting a home visit.").
        include_contact_info:
          type: boolean
          nullable: true
          description: Whether to include business contact info in AI guidance context.
        include_services:
          type: boolean
          nullable: true
          description: Whether to include business services in AI guidance context.
        include_products:
          type: boolean
          nullable: true
          description: Whether to include business products in AI guidance context.
        include_booking_policies:
          type: boolean
          nullable: true
          description: Whether to include booking policies in AI guidance context.
        include_terms_of_service:
          type: boolean
          nullable: true
          description: Whether to include terms of service in AI guidance context.
        allow_chat_based_online_scheduling:
          type: boolean
          nullable: true
          default: true
          description: Whether the AI receptionist may complete a booking inside the chat. Independent of the business's own online-scheduling setting — both must be on for in-chat booking to run; when off, the receptionist offers a link to the booking screen instead. Defaults to true. (e.g., true, false)
        guidance_urls:
          type: array
          nullable: true
          items:
            type: string
            format: uri
          description: Extra URLs whose content is merged into AI guidance.
        ai_actions:
          type: array
          nullable: true
          description: AI proactive action behavior.
          items:
            type: object
            properties:
              action_uid:
                type: string
                description: Portal action UID.
              action_key:
                type: string
                description: Action key/type (e.g., "schedule", "contact").
              should_offer:
                type: boolean
                description: Whether the AI should proactively suggest this action.
              when_to_offer:
                type: string
                nullable: true
                maxLength: 200
                description: Guidance text for when the AI should suggest this action.
            required:
            - action_uid
            - action_key
            - should_offer
        receptionist_enabled:
          type: boolean
          nullable: true
          default: true
          description: 'Whether the AI Receptionist is enabled. **false** turns the AI off for new conversations: website visitors can leave a message, messages from messaging apps go to the inbox, and calls go to voicemail. **true** or null runs the AI until the monthly AI chat quota is used up. Defaults to true. A business with no AiReceptionistConfiguration at all (GET returns 404) has the AI Receptionist off until a configuration is saved (e.g., true, false or null).'
  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


# --- truncated at 32 KB (32 KB total) ---
# Full source: https://artifacts.apis.io/vcita/openapi/vcita-ai-chat-configuration-api-openapi.yml