openapi.yaml

openapi: 3.0.0
info:
  title: matrix2acrobits
  version: 1.0.0
  description: API proxy to adapt Acrobits Cloud Softphone to Matrix.
servers:
  - url: http://localhost:8080
    description: Local development server
paths:
  /api/client/fetch_messages:
    post:
      summary: Fetch Messages
      operationId: fetchMessages
      description: |
        Checks for new incoming messages by performing a Matrix /sync on behalf of the user.
        Authentication is performed against an external authentication service (2-step flow):
        1. POST /api/login with username and password to get JWT token
        2. GET /api/chat?users=1 with Bearer token to fetch user mappings and verify chat capability
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - username
                - password
              properties:
                username:
                  type: string
                  description: The extension/username (format can be user@domain), which is sent to the external auth service.
                password:
                  type: string
                  description: Password used to authenticate via the external auth service.
                last_id:
                  type: string
                  description: The 'since' token from the last sync.
                last_sent_id:
                  type: string
                  description: The message id of the last sent message.
                device:
                  type: string
                  description: Device identifier (e.g., 'ACROBITS').
      responses:
        '200':
          description: Successful sync
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FetchMessagesResponse'
        '401':
          description: Authentication failed (e.g., user not in AS namespace).
  
  /api/client/send_message:
    post:
      summary: Send Message
      operationId: sendMessage
      description: |
        Sends an outgoing message on behalf of a user.

        The `from` field can be:
        - A full Matrix ID (e.g., @user:server.com) - used directly
        - A phone number (e.g., +1234567890) - resolved to Matrix ID via phone-to-Matrix mapping if available

        If a phone number is provided and a mapping exists, the message is sent on behalf of the mapped Matrix user.
        If a phone number is provided but no mapping exists, the phone number is used as the sender ID.

        Authentication is performed against an external authentication service (2-step flow):
        1. POST /api/login with username and password to get JWT token
        2. GET /api/chat?users=1 with Bearer token to fetch user mappings and verify chat capability
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - from
                - to
                - body
                - password
              properties:
                from:
                  type: string
                  description: The sender - either a full Matrix ID (e.g., @user:server.com) or a phone number (e.g., +1234567890).
                password:
                  type: string
                  description: Password used to authenticate the sender via the external auth service.
                to:
                  type: string
                  description: Recipient Matrix ID, Alias, or mapped phone number.
                body:
                  type: string
                  description: The message content.
                content_type:
                  type: string
                  default: text/plain
                disposition_notification:
                  type: string
                  description: Opaque string for read receipts.
      responses:
        '200':
          description: Message sent successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message_id:
                    type: string
                    description: The Matrix event ID of the sent message.
        '400':
          description: Invalid request or recipient.
        '401':
          description: Authentication failed (e.g., user not in AS namespace).

  /api/client/push_token_report:
    post:
      summary: Report Push Token
      operationId: pushTokenReport
      description: |
        Receives and stores device push tokens from Acrobits clients.
        The tokens are persisted in a SQLite database for later use in push notification delivery.
        This endpoint follows the Acrobits Push Token Reporter API specification for POST JSON requests.
        
        Authentication is performed against an external authentication service (2-step flow):
        1. POST /api/login with username and password to get JWT token
        2. GET /api/chat?users=1 with Bearer token to fetch user mappings and verify chat capability
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PushTokenReportRequest'
      responses:
        '200':
          description: Push token accepted and stored
          content:
            application/json:
              schema:
                type: object
                description: Empty JSON object response
        '400':
          description: Invalid request payload (e.g., missing selector).
        '500':
          description: Server error (e.g., database unavailable).
      example:
        request:
          selector: "12869E0E6E553673C54F29105A0647204C416A2A:7C3A0D14"
          token_msgs: "QVBBOTFiRzlhcVd2bW54bllCWldHOWh4dnRrZ3pUWFNvcGZpdWZ6bWM2dFAzS2J"
          appid_msgs: "com.cloudsoftphone.app"
          token_calls: "Udl99X2JFP1bWwS5gR/wGeLE1hmAB2CMpr1Ej0wxkrY="
          appid_calls: "com.cloudsoftphone.app.pushkit"
        response:
          {}



  /api/internal/push_tokens:
    get:
      summary: Get all push tokens
      description: |
        Returns the contents of the push token database. Requires the `X-Super-Admin-Token` header
        and can only be accessed from localhost.
      parameters:
        - in: header
          name: X-Super-Admin-Token
          schema:
            type: string
          required: true
          description: The Application Service token (as_token).
      responses:
        '200':
          description: Push tokens retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PushToken'
        '401':
          description: Invalid admin token.
        '403':
          description: Access denied (not from localhost).
        '500':
          description: Server error (e.g., database unavailable).
    delete:
      summary: Reset push token database
      description: |
        Deletes all push tokens from the database. Requires the `X-Super-Admin-Token` header
        and can only be accessed from localhost.
      parameters:
        - in: header
          name: X-Super-Admin-Token
          schema:
            type: string
          required: true
          description: The Application Service token (as_token).
      responses:
        '200':
          description: Push tokens database reset successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "reset"
        '401':
          description: Invalid admin token.
        '403':
          description: Access denied (not from localhost).
        '500':
          description: Server error (e.g., database unavailable).

  /_matrix/push/v1/notify:
    post:
      summary: Matrix Push Gateway Notify
      operationId: matrixPushNotify
      description: |
        Endpoint used by a Matrix homeserver (push gateway) to deliver push notifications
        to this proxy. The proxy will translate Matrix notifications into Acrobits PNM
        requests and return any rejected pushkeys in the response.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MatrixPushNotifyRequest'
      responses:
        '200':
          description: Notification processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatrixPushNotifyResponse'
        '400':
          description: Invalid request payload
        '500':
          description: Server error while processing notification
  /_matrix/app/v1/transactions/{txnId}:
    put:
      summary: Application Service Transaction
      description: |
        Endpoint used by a Matrix homeserver to deliver application-service transactions
        (batches of events) to the Application Service. The proxy accepts the payload,
        logs it for debugging and acknowledges with 200 OK.
      parameters:
        - in: path
          name: txnId
          required: true
          schema:
            type: string
          description: Transaction id assigned by the homeserver
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Application Service transaction payload (events array and other fields)
              additionalProperties: true
      responses:
        '200':
          description: Transaction received and acknowledged
        '400':
          description: Invalid payload
components:
  schemas:
    SMS:
      type: object
      description: A message following the Acrobits Modern API format.
      properties:
        sms_id:
          type: string
          description: Unique identifier (Matrix Event ID).
        sending_date:
          type: string
          format: date-time
          description: RFC 3339 timestamp when the message was sent.
        sender:
          type: string
          description: Sender identifier (phone number or user name). Only present in received messages.
        recipient:
          type: string
          description: Recipient identifier (phone number or user name). Only present in sent messages.
        sms_text:
          type: string
          description: Message body (UTF-8 encoded).
        content_type:
          type: string
          description: MIME content-type. Defaults to text/plain if omitted.
        disposition_notification:
          type: string
          description: Opaque string from Send Message request. Can be omitted if empty.
        displayed:
          type: boolean
          description: True if message has already been displayed on another device. Only in received messages.
        stream_id:
          type: string
          description: Identifier for the conversation stream (Room ID or identifier).
    FetchMessagesResponse:
      type: object
      description: Response from the fetch_messages endpoint following Acrobits Modern API specification.
      properties:
        date:
          type: string
          format: date-time
          description: Current server time in RFC 3339 format (used to synchronize timestamps).
        received_smss:
          type: array
          items:
            $ref: '#/components/schemas/SMS'
          description: Array of received messages. Sorted by sending_date in ascending order (oldest first).
        sent_smss:
          type: array
          items:
            $ref: '#/components/schemas/SMS'
          description: Array of sent messages. Sorted by sending_date in ascending order (oldest first).
    MatrixPushNotifyRequest:
      type: object
      properties:
        notification:
          $ref: '#/components/schemas/MatrixNotification'
    MatrixNotification:
      type: object
      properties:
        event_id:
          type: string
        room_id:
          type: string
        type:
          type: string
        sender:
          type: string
        sender_display_name:
          type: string
        content:
          type: object
          additionalProperties: true
        counts:
          $ref: '#/components/schemas/MatrixCounts'
        devices:
          type: array
          items:
            $ref: '#/components/schemas/MatrixDevice'
    MatrixCounts:
      type: object
      properties:
        unread:
          type: integer
        missed_calls:
          type: integer
    MatrixDevice:
      type: object
      properties:
        app_id:
          type: string
        pushkey:
          type: string
        pushkey_ts:
          type: integer
        tweaks:
          type: object
          additionalProperties: true
    MatrixPushNotifyResponse:
      type: object
      properties:
        rejected:
          type: array
          items:
            type: string
    PushTokenReportRequest:
      type: object
      required:
        - selector
        - password
      properties:
        username:
          type: string
          description: The extension or selector username reporting the token.
        password:
          type: string
          description: Password used to authenticate the extension via the external auth service.
        selector:
          type: string
          description: |
            SHA1 hash with suffix that uniquely identifies the account.
            Used to reference the account in push notification delivery requests.
            Example: 12869E0E6E553673C54F29105A0647204C416A2A:7C3A0D14
        token_msgs:
          type: string
          description: |
            Base64-encoded push token for regular notifications (APNs remote-notification).
            Required for iOS push notifications.
        appid_msgs:
          type: string
          description: |
            Apple application ID for regular notifications.
            Used in conjunction with token_msgs.
        token_calls:
          type: string
          description: |
            Base64-encoded push token for VoIP/incoming call notifications (APNs pushkit).
            Required for iOS incoming call notifications.
        appid_calls:
          type: string
          description: |
            Apple application ID for incoming call notifications.
            Used in conjunction with token_calls.
    PushToken:
      type: object
      properties:
        id:
          type: integer
          description: Internal database ID.
        selector:
          type: string
          description: |
            SHA1 hash with suffix that uniquely identifies the account.
            Example: 12869E0E6E553673C54F29105A0647204C416A2A:7C3A0D14
        token_msgs:
          type: string
          description: Base64-encoded push token for regular notifications.
        appid_msgs:
          type: string
          description: Apple application ID for regular notifications.
        token_calls:
          type: string
          description: Base64-encoded push token for VoIP/incoming call notifications.
        appid_calls:
          type: string
          description: Apple application ID for incoming call notifications.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the push token was first created (RFC 3339).
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the push token was last updated (RFC 3339).