Microsoft Bot Framework Channel API

openapi: 3.2.0
info:
  title: Azure Bot Service Channel API
  description: Azure Bot Service is a platform for creating smart conversational agents.
  version: '2022-09-15'
servers:
- url: https://management.azure.com
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: Channels_Create
      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'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BotChannel'
        description: The parameters to provide for the created bot.
        required: true
      summary: Channels create
      x-summary-source: derived
    patch:
      tags:
      - Channel
      description: Updates a Channel registration for a Bot Service
      operationId: Channels_Update
      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'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BotChannel'
        description: The parameters to provide for the created bot.
        required: true
      summary: Channels update
      x-summary-source: derived
    delete:
      tags:
      - Channel
      description: Deletes a Channel registration from a Bot Service
      operationId: Channels_Delete
      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: Channels delete
      x-summary-source: derived
    get:
      tags:
      - Channel
      description: Returns a BotService Channel registration specified by the parameters.
      operationId: Channels_Get
      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: Channels get
      x-summary-source: derived
  ? /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: Channels_ListWithKeys
      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: Channels list with keys
      x-summary-source: derived
  ? /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: Channels_ListByResourceGroup
      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: Channels list by resource group
      x-summary-source: derived
  ? /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: DirectLine_RegenerateKeys
      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'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SiteInfo'
        description: The parameters to provide for the created bot.
        required: true
      summary: Direct line regenerate keys
      x-summary-source: derived
  ? /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: Email_CreateSignInUrl
      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: Email create sign in url
      x-summary-source: derived
components:
  schemas:
    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
    ErrorBody:
      properties:
        code:
          type: string
          description: error code
        message:
          type: string
          description: error message
      description: Bot Service error body.
      required:
      - code
      - message
    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
    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.
    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
    Error:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
          description: The error body.
      description: Bot Service error object.
    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
    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.
        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
    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
    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.
    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
    CreateEmailSignInUrlResponseProperties:
      type: object
      description: The set of properties specific to sign in url
      properties:
        url:
          description: Sign in url.
          type: string
    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
    SkuName:
      type: string
      description: The name of SKU.
      enum:
      - F0
      - S1
      x-ms-enum:
        name: SkuName
        modelAsString: true
  parameters:
    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
    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
    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_.-]*$
    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_.-]*$
  securitySchemes:
    azure_auth:
      type: oauth2
      flows:
        implicit:
          scopes:
            user_impersonation: impersonate your user account
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
      description: Azure Active Directory OAuth2 Flow