Microsoft Azure Bot API

openapi: 3.2.0
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Bot API
tags:
- name: Bot
paths:
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.BotService/botServices/{resourceName}
  : put:
      tags:
      - Bot
      description: Creates a Bot Service. Bot Service is a resource group wide resource type.
      operationId: microsoftAzureBotsCreate
      x-ms-examples:
        Create Bot:
          $ref: ./examples/CreateBot.json
      parameters:
      - $ref: '#/components/parameters/resourceGroupNameParameter'
      - $ref: '#/components/parameters/resourceNameParameter'
      - $ref: '#/components/parameters/apiVersionParameter'
      - $ref: '#/components/parameters/subscriptionIdParameter'
      responses:
        '200':
          description: If resource is created successfully or already existed, the service should return 200 (OK).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bot'
        '201':
          description: If resource is created successfully, the service should return 201 (Created). Execution to continue asynchronously.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bot'
        default:
          description: Error response describing why the operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Microsoft Azure Put Subscriptions Subscriptionid Resourcegroups Resourcegroupname Providers Microsoft Botservice Botservices Resourcename
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Bot'
        description: The parameters to provide for the created bot.
        required: true
    patch:
      tags:
      - Bot
      description: Updates a Bot Service
      operationId: microsoftAzureBotsUpdate
      x-ms-examples:
        Update Bot:
          $ref: ./examples/UpdateBot.json
      parameters:
      - $ref: '#/components/parameters/resourceGroupNameParameter'
      - $ref: '#/components/parameters/resourceNameParameter'
      - $ref: '#/components/parameters/apiVersionParameter'
      - $ref: '#/components/parameters/subscriptionIdParameter'
      responses:
        '200':
          description: 'The resource provider should return 200 (OK) to indicate that the operation completed successfully. '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bot'
        '201':
          description: If resource is updated successfully, the service should return 201 (Created). Execution to continue asynchronously.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bot'
        default:
          description: Error response describing why the operation failed. If the resource group *or* resource does not exist, 404 (NotFound) should be returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Microsoft Azure Patch Subscriptions Subscriptionid Resourcegroups Resourcegroupname Providers Microsoft Botservice Botservices Resourcename
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Bot'
        description: The parameters to provide for the created bot.
        required: true
    delete:
      tags:
      - Bot
      description: 'Deletes a Bot Service from the resource group. '
      operationId: microsoftAzureBotsDelete
      x-ms-examples:
        Delete Bot:
          $ref: ./examples/DeleteBot.json
      parameters:
      - $ref: '#/components/parameters/resourceGroupNameParameter'
      - $ref: '#/components/parameters/resourceNameParameter'
      - $ref: '#/components/parameters/apiVersionParameter'
      - $ref: '#/components/parameters/subscriptionIdParameter'
      responses:
        '200':
          description: A 200 (OK) should be returned if the object exists and was deleted successfully;
        '204':
          description: a 204 (NoContent) should be used if the resource does not exist and the request is well formed.
        default:
          description: Error response describing why the operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Microsoft Azure Delete Subscriptions Subscriptionid Resourcegroups Resourcegroupname Providers Microsoft Botservice Botservices Resourcename
    get:
      tags:
      - Bot
      description: Returns a BotService specified by the parameters.
      operationId: microsoftAzureBotsGet
      x-ms-examples:
        Get Bot:
          $ref: ./examples/GetBot.json
      parameters:
      - $ref: '#/components/parameters/resourceGroupNameParameter'
      - $ref: '#/components/parameters/resourceNameParameter'
      - $ref: '#/components/parameters/apiVersionParameter'
      - $ref: '#/components/parameters/subscriptionIdParameter'
      responses:
        '200':
          description: 'The resource provider should return 200 (OK) to indicate that the operation completed successfully. '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bot'
        default:
          description: Error response describing why the operation failed. If the resource group *or* resource does not exist, 404 (NotFound) should be returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Microsoft Azure Get Subscriptions Subscriptionid Resourcegroups Resourcegroupname Providers Microsoft Botservice Botservices Resourcename
  /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.BotService/botServices:
    get:
      tags:
      - Bot
      description: Returns all the resources of a particular type belonging to a resource group
      operationId: microsoftAzureBotsListbyresourcegroup
      x-ms-examples:
        List Bots by Resource Group:
          $ref: ./examples/ListBotsByResourceGroup.json
      parameters:
      - $ref: '#/components/parameters/resourceGroupNameParameter'
      - $ref: '#/components/parameters/subscriptionIdParameter'
      - $ref: '#/components/parameters/apiVersionParameter'
      responses:
        '200':
          description: "The resource provider should return 200 (OK) to indicate that the operation completed successfully. For other errors (e.g. internal errors) use the appropriate HTTP error code.\nThe nextLink field is expected to point to the URL the client should use to fetch the next page (per server side paging). This matches the OData guidelines for paged responses here. If a resource provider does not support paging, it should return the same body (JSON object with “value” property) but omit nextLink entirely (or set to null, *not* empty string) for future compatibility.\nThe nextLink should be implemented using following query parameters:\n· skipToken: opaque token that allows the resource provider to skip resources already enumerated. This value is defined and returned by the RP after first request via nextLink.\n· top: the optional client query parameter which defines the maximum number of records to be returned by the server.\nImplementation details:\n· NextLink may include all the query parameters (specifically OData $filter) used by the client in the first query. \n· Server may return less records than requested with nextLink. Returning zero records with NextLink is an acceptable response. \nClients must fetch records until the nextLink is not returned back / null. Clients should never rely on number of returned records to determinate if pagination is completed."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BotResponseList'
        default:
          description: Error response describing why the operation failed. If the resource group does not exist, 404 (NotFound) will be returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ms-pageable:
        nextLinkName: nextLink
      summary: Microsoft Azure Get Subscriptions Subscriptionid Resourcegroups Resourcegroupname Providers Microsoft Botservice Botservices
  /subscriptions/{subscriptionId}/providers/Microsoft.BotService/botServices:
    get:
      tags:
      - Bot
      description: Returns all the resources of a particular type belonging to a subscription.
      operationId: microsoftAzureBotsList
      x-ms-examples:
        List Bots by Subscription:
          $ref: ./examples/ListBotsBySubscription.json
      parameters:
      - $ref: '#/components/parameters/apiVersionParameter'
      - $ref: '#/components/parameters/subscriptionIdParameter'
      responses:
        '200':
          description: 'The resource provider should return 200 (OK) to indicate that the operation completed successfully. For other errors (e.g. internal errors) use the appropriate HTTP error code.

            The nextLink field is expected to point to the URL the client should use to fetch the next page (per server side paging). This matches the OData guidelines for paged responses. If a resource provider does not support paging, it should return the same body but leave nextLink empty for future compatibility.

            For a detailed explanation of each field in the response body, please refer to the request body description in the PUT resource section. '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BotResponseList'
        default:
          description: Error response describing why the operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ms-pageable:
        nextLinkName: nextLink
      summary: Microsoft Azure Get Subscriptions Subscriptionid Providers Microsoft Botservice Botservices
  /providers/Microsoft.BotService/checkNameAvailability:
    post:
      tags:
      - Bot
      description: Check whether a bot name is available.
      operationId: microsoftAzureBotsGetchecknameavailability
      x-ms-examples:
        check Name Availability:
          $ref: ./examples/CheckNameAvailability.json
      parameters:
      - $ref: '#/components/parameters/apiVersionParameter'
      responses:
        '200':
          description: 'The resource provider should return 200 (OK) to indicate that the operation completed successfully. For other errors (e.g. internal errors) use the appropriate HTTP error code.

            The nextLink field is expected to point to the URL the client should use to fetch the next page (per server side paging). This matches the OData guidelines for paged responses. If a resource provider does not support paging, it should return the same body but leave nextLink empty for future compatibility.

            For a detailed explanation of each field in the response body, please refer to the request body description in the PUT resource section. '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckNameAvailabilityResponseBody'
        default:
          description: Error response describing why the operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Microsoft Azure Post Providers Microsoft Botservice Checknameavailability
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckNameAvailabilityRequestBody'
        description: The request body parameters to provide for the check name availability request
        required: true
components:
  schemas:
    Bot:
      type: object
      description: Bot resource definition
      allOf:
      - $ref: '#/components/schemas/Resource'
      properties:
        properties:
          $ref: '#/components/schemas/BotProperties'
          description: The set of properties specific to bot resource
    SkuName:
      type: string
      description: The name of SKU.
      enum:
      - F0
      - S1
      x-ms-enum:
        name: SkuName
        modelAsString: true
    BotProperties:
      properties:
        displayName:
          type: string
          description: The Name of the bot
        description:
          type: string
          description: The description of the bot
        iconUrl:
          type: string
          description: The Icon Url of the bot
          default: ''
        endpoint:
          type:
          - string
          - 'null'
          description: The bot's endpoint
        endpointVersion:
          type: string
          readOnly: true
          description: The bot's endpoint version
        allSettings:
          description: Contains resource all settings defined as key/value pairs.
          type: object
          additionalProperties:
            type: string
        parameters:
          description: Contains resource parameters defined as key/value pairs.
          type: object
          additionalProperties:
            type: string
        manifestUrl:
          type: string
          description: The bot's manifest url
        msaAppType:
          type: string
          description: Microsoft App Type for the bot
          enum:
          - UserAssignedMSI
          - SingleTenant
          - MultiTenant
          x-ms-enum:
            name: msaAppType
            modelAsString: true
        msaAppId:
          type: string
          description: Microsoft App Id for the bot
          x-ms-mutability:
          - create
          - read
        msaAppTenantId:
          type: string
          description: Microsoft App Tenant Id for the bot
          x-ms-mutability:
          - create
          - read
        msaAppMSIResourceId:
          type: string
          description: Microsoft App Managed Identity Resource Id for the bot
        configuredChannels:
          type: array
          items:
            type: string
          readOnly: true
          description: Collection of channels for which the bot is configured
        enabledChannels:
          type: array
          items:
            type: string
          readOnly: true
          description: Collection of channels for which the bot is enabled
        developerAppInsightKey:
          type: string
          description: The Application Insights key
        developerAppInsightsApiKey:
          type: string
          description: The Application Insights Api Key
        developerAppInsightsApplicationId:
          type: string
          description: The Application Insights App Id
        luisAppIds:
          type: array
          items:
            type: string
          description: Collection of LUIS App Ids
        luisKey:
          type: string
          description: The LUIS Key
        isCmekEnabled:
          type: boolean
          description: Whether Cmek is enabled
          default: false
        cmekKeyVaultUrl:
          type: string
          description: The CMK Url
        cmekEncryptionStatus:
          type: string
          description: The CMK encryption status
          readOnly: true
        tenantId:
          type: string
          description: The Tenant Id for the bot
          x-ms-mutability:
          - create
          - read
        publicNetworkAccess:
          description: Whether the bot is in an isolated network
          enum:
          - Enabled
          - Disabled
          - SecuredByPerimeter
          type: string
          x-ms-enum:
            name: PublicNetworkAccess
            modelAsString: true
          default: Enabled
        isStreamingSupported:
          type: boolean
          description: Whether the bot is streaming supported
          default: false
        isDeveloperAppInsightsApiKeySet:
          type: boolean
          description: Whether the bot is developerAppInsightsApiKey set
          readOnly: true
        migrationToken:
          type: string
          description: Token used to migrate non Azure bot to azure subscription
          readOnly: true
        disableLocalAuth:
          type: boolean
          description: Opt-out of local authentication and ensure only MSI and AAD can be used exclusively for authentication.
        schemaTransformationVersion:
          type:
          - string
          - 'null'
          description: The channel schema transformation version for the bot
          default: null
        storageResourceId:
          type: string
          description: The storage resourceId for the bot
        privateEndpointConnections:
          type: array
          readOnly: true
          description: List of Private Endpoint Connections configured for the bot
          items:
            $ref: ./privatelinks.json#/definitions/PrivateEndpointConnection
        networkSecurityPerimeterConfigurations:
          type: array
          readOnly: true
          description: List of Network Security Perimeter configurations for the bot
          items:
            $ref: ./networksecurityperimeter.json#/definitions/NetworkSecurityPerimeterConfiguration
        openWithHint:
          type: string
          description: The hint to browser (e.g. protocol handler) on how to open the bot for authoring
        appPasswordHint:
          type: string
          description: The hint (e.g. keyVault secret resourceId) on how to fetch the app secret
        provisioningState:
          type: string
          readOnly: true
          description: Provisioning state of the resource
        publishingCredentials:
          type: string
          description: Publishing credentials of the resource
      description: The parameters to provide for the Bot.
      required:
      - displayName
      - endpoint
      - msaAppId
    CheckNameAvailabilityResponseBody:
      description: The response body returned for a request to Bot Service Management to check availability of a bot name.
      type: object
      properties:
        valid:
          description: indicates if the bot name is valid.
          type: boolean
        message:
          description: additional message from the bot management api showing why a bot name is not available
          type: string
        absCode:
          description: response code from ABS
          type: string
          x-ms-nullable: true
    CheckNameAvailabilityRequestBody:
      description: The request body for a request to Bot Service Management to check availability of a bot name.
      type: object
      properties:
        name:
          description: the name of the bot for which availability needs to be checked.
          type: string
        type:
          description: the type of the bot for which availability needs to be checked
          type: string
    Error:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
          description: The error body.
      description: Bot Service error object.
    ErrorBody:
      properties:
        code:
          type: string
          description: error code
        message:
          type: string
          description: error message
      description: Bot Service error body.
      required:
      - code
      - message
    Sku:
      properties:
        name:
          $ref: '#/components/schemas/SkuName'
          description: The sku name
        tier:
          readOnly: true
          type: string
          description: Gets the sku tier. This is based on the SKU name.
          enum:
          - Free
          - Standard
          x-ms-enum:
            name: SkuTier
            modelAsString: true
      required:
      - name
      description: The SKU of the cognitive services account.
    Kind:
      type: string
      description: Indicates the type of bot service
      enum:
      - sdk
      - designer
      - bot
      - function
      - azurebot
      x-ms-enum:
        name: Kind
        modelAsString: true
      x-ms-mutability:
      - create
      - read
    BotResponseList:
      properties:
        nextLink:
          description: The link used to get the next page of bot service resources.
          type: string
        value:
          readOnly: true
          type: array
          items:
            $ref: '#/components/schemas/Bot'
          description: Gets the list of bot service results and their properties.
      description: The list of bot service operation response.
    Resource:
      description: Azure resource
      x-ms-azure-resource: true
      properties:
        id:
          description: Specifies the resource ID.
          type: string
          readOnly: true
        name:
          description: Specifies the name of the resource.
          type: string
          readOnly: true
        location:
          description: Specifies the location of the resource.
          type: string
        type:
          description: Specifies the type of the resource.
          type: string
          readOnly: true
        tags:
          description: Contains resource tags defined as key/value pairs.
          type: object
          additionalProperties:
            type: string
        sku:
          $ref: '#/components/schemas/Sku'
          description: Gets or sets the SKU of the resource.
        kind:
          $ref: '#/components/schemas/Kind'
          description: Required. Gets or sets the Kind of the resource.
        etag:
          type: string
          description: Entity Tag.
        zones:
          type: array
          items:
            type: string
          description: Entity zones
          readOnly: true
  parameters:
    apiVersionParameter:
      name: api-version
      in: query
      required: true
      description: Version of the API to be used with the client request.
      schema:
        type: string
    resourceNameParameter:
      name: resourceName
      x-ms-parameter-location: method
      in: path
      required: true
      description: The name of the Bot resource.
      schema:
        type: string
        maxLength: 64
        minLength: 2
        pattern: ^[a-zA-Z0-9][a-zA-Z0-9_.-]*$
    resourceGroupNameParameter:
      name: resourceGroupName
      x-ms-parameter-location: method
      in: path
      required: true
      description: The name of the Bot resource group in the user subscription.
      schema:
        type: string
        maxLength: 64
        minLength: 2
        pattern: ^[a-zA-Z0-9][a-zA-Z0-9_.-]*$
    subscriptionIdParameter:
      name: subscriptionId
      in: path
      description: Azure Subscription ID.
      required: true
      schema:
        type: string
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/Endpoint'