Azure Communication Services API

openapi: 3.1.0
info:
  title: Microsoft Azure Communication Services API
  description: >-
    Multichannel communication APIs for adding voice, video, chat, SMS, and
    email capabilities to applications.
  version: '2024-03-15'
  contact:
    name: Azure Communication Services Support
    url: https://learn.microsoft.com/en-us/azure/communication-services/
  termsOfService: https://www.microsoft.com/en-us/legal/terms-of-use
externalDocs:
  description: Azure Communication Services REST API Reference
  url: https://learn.microsoft.com/en-us/rest/api/communication/
servers:
  - url: https://{resource}.communication.azure.com
    description: Azure Communication Services Endpoint
    variables:
      resource:
        default: your-resource
        description: Your Communication Services resource name
tags:
  - name: Chat
    description: Manage chat threads and messages
  - name: Email
    description: Send email messages
  - name: Identity
    description: Create and manage communication identities
  - name: SMS
    description: Send SMS messages
security:
  - accessKey: []
paths:
  /identities:
    post:
      operationId: createIdentity
      summary: Microsoft Create an identity
      description: Create a new Communication Services identity.
      tags:
        - Identity
      parameters:
        - $ref: '#/components/parameters/apiVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                createTokenWithScopes:
                  type: array
                  items:
                    type: string
                    enum:
                      - chat
                      - voip
                  description: Also create an access token with these scopes
      responses:
        '201':
          description: Identity created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationIdentityAccessTokenResult'
        '401':
          description: Unauthorized
  /identities/{id}:
    delete:
      operationId: deleteIdentity
      summary: Microsoft Delete an identity
      description: Delete a Communication Services identity and revoke all tokens.
      tags:
        - Identity
      parameters:
        - name: id
          in: path
          required: true
          description: Identifier of the identity to delete
          schema:
            type: string
        - $ref: '#/components/parameters/apiVersion'
      responses:
        '204':
          description: Identity deleted
        '401':
          description: Unauthorized
        '404':
          description: Identity not found
  /identities/{id}/:issueAccessToken:
    post:
      operationId: issueAccessToken
      summary: Microsoft Issue an access token
      description: Issue a new access token for an identity.
      tags:
        - Identity
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/apiVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - scopes
              properties:
                scopes:
                  type: array
                  items:
                    type: string
                    enum:
                      - chat
                      - voip
                expiresInMinutes:
                  type: integer
                  minimum: 60
                  maximum: 1440
                  default: 1440
      responses:
        '200':
          description: Access token issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationIdentityAccessToken'
        '401':
          description: Unauthorized
  /sms:
    post:
      operationId: sendSms
      summary: Microsoft Send an SMS message
      description: Send a single SMS message or a batch of SMS messages.
      tags:
        - SMS
      parameters:
        - $ref: '#/components/parameters/apiVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendSmsRequest'
      responses:
        '202':
          description: SMS accepted for delivery
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmsSendResult'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
  /emails:send:
    post:
      operationId: sendEmail
      summary: Microsoft Send an email
      description: Queues an email message for sending.
      tags:
        - Email
      parameters:
        - $ref: '#/components/parameters/apiVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailMessage'
      responses:
        '202':
          description: Email accepted for delivery
          headers:
            Operation-Location:
              schema:
                type: string
              description: URL to poll for send status
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  status:
                    type: string
                    enum:
                      - NotStarted
                      - Running
                      - Succeeded
                      - Failed
                      - Canceled
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
  /chat/threads:
    post:
      operationId: createChatThread
      summary: Microsoft Create a chat thread
      description: Create a new chat thread.
      tags:
        - Chat
      parameters:
        - $ref: '#/components/parameters/apiVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChatThreadRequest'
      responses:
        '201':
          description: Chat thread created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateChatThreadResult'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
    get:
      operationId: listChatThreads
      summary: Microsoft List chat threads
      description: List all chat threads for the authenticated user.
      tags:
        - Chat
      parameters:
        - $ref: '#/components/parameters/apiVersion'
        - name: maxPageSize
          in: query
          description: Maximum number of threads per page
          schema:
            type: integer
        - name: startTime
          in: query
          description: Start time for the range query
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: List of chat threads
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/ChatThread'
                  nextLink:
                    type: string
        '401':
          description: Unauthorized
  /chat/threads/{chatThreadId}/messages:
    post:
      operationId: sendChatMessage
      summary: Microsoft Send a chat message
      description: Send a message to a chat thread.
      tags:
        - Chat
      parameters:
        - name: chatThreadId
          in: path
          required: true
          description: Chat thread ID
          schema:
            type: string
        - $ref: '#/components/parameters/apiVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - content
              properties:
                content:
                  type: string
                senderDisplayName:
                  type: string
                type:
                  type: string
                  enum:
                    - text
                    - html
                  default: text
      responses:
        '201':
          description: Message sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
    get:
      operationId: listChatMessages
      summary: Microsoft List chat messages
      description: List messages in a chat thread.
      tags:
        - Chat
      parameters:
        - name: chatThreadId
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/apiVersion'
        - name: maxPageSize
          in: query
          schema:
            type: integer
        - name: startTime
          in: query
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: List of messages
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/ChatMessageItem'
                  nextLink:
                    type: string
        '401':
          description: Unauthorized
components:
  securitySchemes:
    accessKey:
      type: apiKey
      name: Authorization
      in: header
      description: HMAC-SHA256 signature authentication
  parameters:
    apiVersion:
      name: api-version
      in: query
      required: true
      description: API version
      schema:
        type: string
        default: '2024-03-15-preview'
  schemas:
    CommunicationIdentityAccessTokenResult:
      type: object
      properties:
        identity:
          type: object
          properties:
            id:
              type: string
        accessToken:
          $ref: '#/components/schemas/CommunicationIdentityAccessToken'
    CommunicationIdentityAccessToken:
      type: object
      properties:
        token:
          type: string
        expiresOn:
          type: string
          format: date-time
    SendSmsRequest:
      type: object
      required:
        - from
        - smsRecipients
        - message
      properties:
        from:
          type: string
          description: Sender phone number in E.164 format
        smsRecipients:
          type: array
          items:
            type: object
            required:
              - to
            properties:
              to:
                type: string
                description: Recipient phone number in E.164 format
        message:
          type: string
          description: The message body (max 2048 characters)
          maxLength: 2048
        smsSendOptions:
          type: object
          properties:
            enableDeliveryReport:
              type: boolean
              default: false
            tag:
              type: string
    SmsSendResult:
      type: object
      properties:
        value:
          type: array
          items:
            type: object
            properties:
              to:
                type: string
              messageId:
                type: string
              httpStatusCode:
                type: integer
              successful:
                type: boolean
              errorMessage:
                type: string
    EmailMessage:
      type: object
      required:
        - senderAddress
        - recipients
        - content
      properties:
        senderAddress:
          type: string
          description: Sender email address
        recipients:
          type: object
          required:
            - to
          properties:
            to:
              type: array
              items:
                type: object
                required:
                  - address
                properties:
                  address:
                    type: string
                  displayName:
                    type: string
            cc:
              type: array
              items:
                type: object
                properties:
                  address:
                    type: string
                  displayName:
                    type: string
            bcc:
              type: array
              items:
                type: object
                properties:
                  address:
                    type: string
                  displayName:
                    type: string
        content:
          type: object
          required:
            - subject
          properties:
            subject:
              type: string
            plainText:
              type: string
            html:
              type: string
    CreateChatThreadRequest:
      type: object
      required:
        - topic
      properties:
        topic:
          type: string
        participants:
          type: array
          items:
            type: object
            required:
              - communicationIdentifier
            properties:
              communicationIdentifier:
                type: object
                properties:
                  communicationUserId:
                    type: string
              displayName:
                type: string
    CreateChatThreadResult:
      type: object
      properties:
        chatThread:
          $ref: '#/components/schemas/ChatThread'
        errors:
          type: object
    ChatThread:
      type: object
      properties:
        id:
          type: string
        topic:
          type: string
        createdOn:
          type: string
          format: date-time
        createdByCommunicationIdentifier:
          type: object
          properties:
            communicationUserId:
              type: string
        deletedOn:
          type: string
          format: date-time
    ChatMessageItem:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        content:
          type: object
          properties:
            message:
              type: string
        senderDisplayName:
          type: string
        createdOn:
          type: string
          format: date-time
        senderCommunicationIdentifier:
          type: object
          properties:
            communicationUserId:
              type: string