Microsoft Azure Channel API

openapi: 3.2.0
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Channel API
tags:
- name: Channel
paths:
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.BotService/botServices/{resourceName}/channels/{channelName}
  : put:
      tags:
      - Channel
      description: Creates a Channel registration for a Bot Service
      operationId: microsoftAzureChannelsCreate
      x-ms-examples:
        Create Channel:
          $ref: ./examples/PutChannel.json
        Create Alexa Channel:
          $ref: ./examples/PutAlexaChannel.json
        Create Email Channel:
          $ref: ./examples/PutEmailChannel.json
        Create Line Channel:
          $ref: ./examples/PutLineChannel.json
        Create DirectLine Speech Channel:
          $ref: ./examples/PutDirectLineSpeechChannel.json
      parameters:
      - $ref: '#/components/parameters/resourceGroupNameParameter'
      - $ref: '#/components/parameters/resourceNameParameter'
      - $ref: '#/components/parameters/channelNameParameter'
      - $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/BotChannel'
        '201':
          description: If resource is created successfully, the service should return 201 (Created). Execution to continue asynchronously.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BotChannel'
        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 Channels Channelname
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BotChannel'
        description: The parameters to provide for the created bot.
        required: true
    patch:
      tags:
      - Channel
      description: Updates a Channel registration for a Bot Service
      operationId: microsoftAzureChannelsUpdate
      x-ms-examples:
        Update Channel:
          $ref: ./examples/UpdateChannel.json
        Update Alexa Channel:
          $ref: ./examples/UpdateAlexaChannel.json
        Update Line Channel:
          $ref: ./examples/UpdateLineChannel.json
        Update DirectLine Speech Channel:
          $ref: ./examples/UpdateDirectLineSpeechChannel.json
      parameters:
      - $ref: '#/components/parameters/resourceGroupNameParameter'
      - $ref: '#/components/parameters/resourceNameParameter'
      - $ref: '#/components/parameters/channelNameParameter'
      - $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/BotChannel'
        '201':
          description: If resource is updated successfully, the service should return 201 (Created). Execution to continue asynchronously.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BotChannel'
        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 Channels Channelname
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BotChannel'
        description: The parameters to provide for the created bot.
        required: true
    delete:
      tags:
      - Channel
      description: Deletes a Channel registration from a Bot Service
      operationId: microsoftAzureChannelsDelete
      x-ms-examples:
        Delete Channel:
          $ref: ./examples/DeleteChannel.json
        Delete DirectLine Speech Channel:
          $ref: ./examples/DeleteDirectLineSpeechChannel.json
      parameters:
      - $ref: '#/components/parameters/resourceGroupNameParameter'
      - $ref: '#/components/parameters/resourceNameParameter'
      - name: channelName
        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_.-]*$
      - $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 Channels Channelname
    get:
      tags:
      - Channel
      description: Returns a BotService Channel registration specified by the parameters.
      operationId: microsoftAzureChannelsGet
      x-ms-examples:
        Get Channel:
          $ref: ./examples/GetChannel.json
        Get Alexa Channel:
          $ref: ./examples/GetAlexaChannel.json
        Get Line Channel:
          $ref: ./examples/GetLineChannel.json
        Get DirectLine Speech Channel:
          $ref: ./examples/GetDirectLineSpeechChannel.json
      parameters:
      - $ref: '#/components/parameters/resourceGroupNameParameter'
      - $ref: '#/components/parameters/resourceNameParameter'
      - name: channelName
        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_.-]*$
      - $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/BotChannel'
        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 Channels Channelname
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.BotService/botServices/{resourceName}/channels/{channelName}/listChannelWithKeys
  : post:
      tags:
      - Channel
      description: Lists a Channel registration for a Bot Service including secrets
      operationId: microsoftAzureChannelsListwithkeys
      x-ms-examples:
        List Channel:
          $ref: ./examples/ListChannel.json
      parameters:
      - $ref: '#/components/parameters/resourceGroupNameParameter'
      - $ref: '#/components/parameters/resourceNameParameter'
      - $ref: '#/components/parameters/channelNameParameter'
      - $ref: '#/components/parameters/apiVersionParameter'
      - $ref: '#/components/parameters/subscriptionIdParameter'
      responses:
        '200':
          description: If resource is retrieved successfully, the service should return 200 (OK).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListChannelWithKeysResponse'
        default:
          description: Error response describing why the operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Microsoft Azure Post Subscriptions Subscriptionid Resourcegroups Resourcegroupname Providers Microsoft Botservice Botservices Resourcename Channels Channelname Listchannelwithkeys
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.BotService/botServices/{resourceName}/channels
  : get:
      tags:
      - Channel
      description: Returns all the Channel registrations of a particular BotService resource
      operationId: microsoftAzureChannelsListbyresourcegroup
      x-ms-examples:
        List Channels by Resource Group:
          $ref: ./examples/ListChannelsByBotService.json
      parameters:
      - $ref: '#/components/parameters/resourceGroupNameParameter'
      - $ref: '#/components/parameters/resourceNameParameter'
      - $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/ChannelResponseList'
        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 Resourcename Channels
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.BotService/botServices/{resourceName}/channels/{channelName}/regeneratekeys
  : post:
      tags:
      - Channel
      description: Regenerates secret keys and returns them for the DirectLine Channel of a particular BotService resource
      operationId: microsoftAzureDirectlineRegeneratekeys
      x-ms-examples:
        Regenerate Keys for DirectLine Channel Site:
          $ref: ./examples/DirectlineRegenerateKeys.json
        Regenerate Keys for WebChat Channel Site:
          $ref: ./examples/WebChatRegenerateKeys.json
      parameters:
      - $ref: '#/components/parameters/resourceGroupNameParameter'
      - $ref: '#/components/parameters/resourceNameParameter'
      - $ref: '#/components/parameters/subscriptionIdParameter'
      - $ref: '#/components/parameters/regenerateKeyschannelNameParameter'
      - $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/BotChannel'
        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'
      summary: Microsoft Azure Post Subscriptions Subscriptionid Resourcegroups Resourcegroupname Providers Microsoft Botservice Botservices Resourcename Channels Channelname Regeneratekeys
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SiteInfo'
        description: The parameters to provide for the created bot.
        required: true
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.BotService/botServices/{resourceName}/createEmailSignInUrl
  : post:
      tags:
      - Channel
      description: Creates an email channel sign in url for a Bot Service
      operationId: microsoftAzureEmailCreatesigninurl
      x-ms-examples:
        Create Url:
          $ref: ./examples/CreateEmailSignInUrl.json
      parameters:
      - $ref: '#/components/parameters/resourceGroupNameParameter'
      - $ref: '#/components/parameters/resourceNameParameter'
      - $ref: '#/components/parameters/apiVersionParameter'
      - $ref: '#/components/parameters/subscriptionIdParameter'
      responses:
        '200':
          description: If url is created successfully, the service should return 200 (OK).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateEmailSignInUrlResponse'
        default:
          description: Error response describing why the operation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Microsoft Azure Post Subscriptions Subscriptionid Resourcegroups Resourcegroupname Providers Microsoft Botservice Botservices Resourcename Createemailsigninurl
components:
  schemas:
    SkuName:
      type: string
      description: The name of SKU.
      enum:
      - F0
      - S1
      x-ms-enum:
        name: SkuName
        modelAsString: true
    Error:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
          description: The error body.
      description: Bot Service error object.
    Site:
      type: object
      properties:
        tenantId:
          type: string
          description: Tenant Id
        siteId:
          type: string
          description: Site Id
          x-ms-mutability:
          - read
          readOnly: true
        siteName:
          type: string
          description: Site name
          x-ms-mutability:
          - create
          - read
        key:
          type: string
          description: Primary key. Value only returned through POST to the action Channel List API, otherwise empty.
          x-ms-mutability:
          - read
          readOnly: true
        key2:
          type: string
          description: Secondary key. Value only returned through POST to the action Channel List API, otherwise empty.
          x-ms-mutability:
          - read
          readOnly: true
        isEnabled:
          type: boolean
          description: Whether this site is enabled for DirectLine channel
        isTokenEnabled:
          type: boolean
          description: Whether this site is token enabled for channel
          readOnly: true
        isEndpointParametersEnabled:
          type: boolean
          description: Whether this site is EndpointParameters enabled for channel
        isDetailedLoggingEnabled:
          type: boolean
          description: Whether this site is disabled detailed logging for
        isBlockUserUploadEnabled:
          type:
          - boolean
          - 'null'
          description: Whether this site is enabled for block user upload.
          default: null
        isNoStorageEnabled:
          type: boolean
          description: Whether this no-storage site is disabled detailed logging for
        eTag:
          type: string
          description: Entity Tag
        appId:
          type: string
          description: DirectLine application id
        isV1Enabled:
          type: boolean
          description: Whether this site is enabled for Bot Framework V1 protocol.
          x-ms-mutability:
          - create
          - read
        isV3Enabled:
          type: boolean
          description: Whether this site is enabled for Bot Framework V3 protocol.
        isSecureSiteEnabled:
          type: boolean
          description: Whether this site is enabled for authentication with Bot Framework.
        trustedOrigins:
          type: array
          description: List of Trusted Origin URLs for this site. This field is applicable only if isSecureSiteEnabled is True.
          items:
            type: string
        isWebChatSpeechEnabled:
          type: boolean
          description: Whether this site is enabled for Webchat Speech
          default: false
        isWebchatPreviewEnabled:
          type: boolean
          description: Whether this site is enabled for preview versions of Webchat
          default: false
      required:
      - isEnabled
      - siteName
      description: A site for the channel
    ListChannelWithKeysResponse:
      type: object
      description: The ARM channel of list channel with keys operation response.
      allOf:
      - $ref: '#/components/schemas/BotChannel'
      properties:
        resource:
          $ref: '#/components/schemas/Channel'
          description: The set of properties specific to bot channel resource
        setting:
          $ref: '#/components/schemas/ChannelSettings'
          description: Channel settings
        provisioningState:
          type: string
          description: Provisioning state of the resource
        entityTag:
          type: string
          description: Entity tag of the resource
        changedTime:
          type: string
          description: Changed time of the resource
    SiteInfo:
      properties:
        siteName:
          type: string
          description: The site name
          x-ms-mutability:
          - create
          - read
        key:
          type: string
          description: Determines which key is to be regenerated
          enum:
          - key1
          - key2
          x-ms-enum:
            name: key
            modelAsString: false
      description: Site information for WebChat or DirectLine Channels to identify which site to regenerate keys for.
      type: object
      required:
      - siteName
      - key
    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
    CreateEmailSignInUrlResponseProperties:
      type: object
      description: The set of properties specific to sign in url
      properties:
        url:
          description: Sign in url.
          type: string
    ChannelResponseList:
      properties:
        nextLink:
          description: The link used to get the next page of bot service channel resources.
          type: string
        value:
          readOnly: true
          type: array
          items:
            $ref: '#/components/schemas/BotChannel'
          description: Gets the list of bot service channel results and their properties.
      description: The list of bot service channel operation response.
    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
    CreateEmailSignInUrlResponse:
      type: object
      description: The ARM create email sign in url operation response.
      properties:
        id:
          description: Specifies the resource ID.
          type: string
          readOnly: true
        location:
          description: Specifies the location of the resource.
          type: string
        properties:
          $ref: '#/components/schemas/CreateEmailSignInUrlResponseProperties'
          description: The set of properties specific to sign in url
    BotChannel:
      type: object
      description: Bot channel resource definition
      allOf:
      - $ref: '#/components/schemas/Resource'
      properties:
        properties:
          $ref: '#/components/schemas/Channel'
          description: The set of properties specific to bot channel resource
    ChannelSettings:
      type: object
      description: Channel settings definition
      properties:
        extensionKey1:
          type: string
          description: The extensionKey1
          default: ''
        extensionKey2:
          type: string
          description: The extensionKey2
          default: ''
        sites:
          type: array
          items:
            $ref: '#/components/schemas/Site'
          description: The list of sites
        channelId:
          type: string
          description: The channel id
        channelDisplayName:
          type: string
          description: The channel display name
        botId:
          type: string
          description: The bot id
        botIconUrl:
          type: string
          description: The bot icon url
        isEnabled:
          type: boolean
          description: Whether this channel is enabled for the bot
        disableLocalAuth:
          type: boolean
          description: Opt-out of local authentication and ensure only MSI and AAD can be used exclusively for authentication.
        requireTermsAgreement:
          type: boolean
          description: Whether customer needs to agree to new terms.
          x-ms-nullable: true
    Channel:
      type: object
      description: Channel definition
      discriminator:
        propertyName: channelName
      properties:
        channelName:
          type: string
          description: The channel name
        etag:
          type:
          - string
          - 'null'
          description: Entity Tag of the resource
          x-ms-mutability:
          - create
          - read
        provisioningState:
          type: string
          readOnly: true
          description: Provisioning state of the resource
        location:
          description: Specifies the location of the resource.
          type: string
          default: global
      required:
      - channelName
  parameters:
    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_.-]*$
    regenerateKeyschannelNameParameter:
      name: channelName
      x-ms-parameter-location: method
      in: path
      required: true
      x-ms-enum:
        name: regenerateKeysChannelName
        modelAsString: false
        values:
        - value: WebChatChannel
        - value: DirectLineChannel
      description: The name of the Channel resource for which keys are to be regenerated.
      schema:
        type: string
        enum:
        - WebChatChannel
        - DirectLineChannel
    subscriptionIdParameter:
      name: subscriptionId
      in: path
      description: Azure Subscription ID.
      required: true
      schema:
        type: string
    apiVersionParameter:
      name: api-version
      in: query
      required: true
      description: Version of the API to be used with the client request.
      schema:
        type: string
    channelNameParameter:
      name: channelName
      x-ms-parameter-location: method
      in: path
      required: true
      x-ms-enum:
        name: channelName
        modelAsString: false
        values:
        - value: AlexaChannel
        - value: FacebookChannel
        - value: EmailChannel
        - value: KikChannel
        - value: TelegramChannel
        - value: SlackChannel
        - value: MsTeamsChannel
        - value: SkypeChannel
        - value: WebChatChannel
        - value: DirectLineChannel
        - value: SmsChannel
        - value: LineChannel
        - value: DirectLineSpeechChannel
        - value: OutlookChannel
        - value: Omnichannel
        - value: TelephonyChannel
        - value: AcsChatChannel
        - value: SearchAssistant
        - value: M365Extensions
      description: The name of the Channel resource.
      schema:
        type: string
        enum:
        - AlexaChannel
        - FacebookChannel
        - EmailChannel
        - KikChannel
        - TelegramChannel
        - SlackChannel
        - MsTeamsChannel
        - SkypeChannel
        - WebChatChannel
        - DirectLineChannel
        - SmsChannel
        - LineChannel
        - DirectLineSpeechChannel
        - OutlookChannel
        - Omnichannel
        - TelephonyChannel
        - AcsChatChannel
        - SearchAssistant
        - M365Extensions
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/Endpoint'