RingCentral API — High Volume SMS

naftiko: 1.0.0-alpha2
info:
  label: RingCentral API — High Volume SMS
  description: 'RingCentral API — High Volume SMS. 8 operations. Lead operation: Send A2P SMS. Self-contained Naftiko capability
    covering one Ringcentral business surface.'
  tags:
  - Ringcentral
  - High Volume SMS
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    RINGCENTRAL_API_KEY: RINGCENTRAL_API_KEY
capability:
  consumes:
  - type: http
    namespace: platform-high-volume-sms
    baseUri: https://platform.ringcentral.com
    description: RingCentral API — High Volume SMS business capability. Self-contained, no shared references.
    resources:
    - name: restapi-v1.0-account-accountId-a2p-sms-batches
      path: /restapi/v1.0/account/{accountId}/a2p-sms/batches
      operations:
      - name: createa2psms
        method: POST
        description: Send A2P SMS
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: lista2pbatches
        method: GET
        description: List A2P SMS Batches
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: from
          in: query
          type: string
          description: Phone number in E.164 format from which the messages are going to be sent
        - name: status
          in: query
          type: array
          description: A list of batch statuses to filter the results
        - name: pageToken
          in: query
          type: string
          description: The page token of the page to be retrieved
        - name: perPage
          in: query
          type: integer
          description: The number of records to be returned per page
    - name: restapi-v1.0-account-accountId-a2p-sms-batches-batchId
      path: /restapi/v1.0/account/{accountId}/a2p-sms/batches/{batchId}
      operations:
      - name: reada2pbatch
        method: GET
        description: Get A2P SMS Batch
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: restapi-v1.0-account-accountId-a2p-sms-messages
      path: /restapi/v1.0/account/{accountId}/a2p-sms/messages
      operations:
      - name: lista2psms
        method: GET
        description: List A2P SMS Messages
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: view
          in: query
          type: string
          description: Indicates if the response has to be detailed, includes text in the response if detailed
        - name: phoneNumber
          in: query
          type: array
          description: List of phone numbers (specified in 'to' or 'from' fields of a message) to filter the results. Maximum
            number of phone numbers allowed to be specified as filter
        - name: pageToken
          in: query
          type: string
          description: The page token of the page to be retrieved.
        - name: perPage
          in: query
          type: integer
          description: The number of messages to be returned per request
    - name: restapi-v1.0-account-accountId-a2p-sms-messages-messageId
      path: /restapi/v1.0/account/{accountId}/a2p-sms/messages/{messageId}
      operations:
      - name: reada2psms
        method: GET
        description: Get A2P SMS
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: messageId
          in: path
          type: string
          description: Internal identifier of a message to be retrieved
          required: true
    - name: restapi-v1.0-account-accountId-a2p-sms-opt-outs
      path: /restapi/v1.0/account/{accountId}/a2p-sms/opt-outs
      operations:
      - name: reada2psmsoptouts
        method: GET
        description: List Opted Out Numbers
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: from
          in: query
          type: string
          description: The sender's phone number in [E.164](https://www.itu.int/rec/T-REC-E.164-201011-I) format for filtering
            messages.
        - name: to
          in: query
          type: string
          description: The receiver's phone number (`to` field) in [E.164](https://www.itu.int/rec/T-REC-E.164-201011-I) format
            for filtering messages
        - name: status
          in: query
          type: string
          description: The status (opted out, opted in, or both) to be used as the filter
        - name: pageToken
          in: query
          type: string
          description: The page token of the page to be retrieved
        - name: perPage
          in: query
          type: integer
          description: The number of records to be returned for the page
    - name: restapi-v1.0-account-accountId-a2p-sms-opt-outs-bulk-assign
      path: /restapi/v1.0/account/{accountId}/a2p-sms/opt-outs/bulk-assign
      operations:
      - name: adda2psmsoptouts
        method: POST
        description: Add Opt-In/Out Numbers
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: restapi-v1.0-account-accountId-a2p-sms-statuses
      path: /restapi/v1.0/account/{accountId}/a2p-sms/statuses
      operations:
      - name: aggregatea2psmsstatuses
        method: GET
        description: List A2P SMS Statuses
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: phoneNumber
          in: query
          type: array
          description: List of phone numbers (specified in 'to' or 'from' fields of a message) to filter the results. Maximum
            number of phone numbers allowed to be specified as filter
    authentication:
      type: bearer
      token: '{{env.RINGCENTRAL_API_KEY}}'
  exposes:
  - type: rest
    namespace: platform-high-volume-sms-rest
    port: 8080
    description: REST adapter for RingCentral API — High Volume SMS. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/restapi/v1-0/account/{accountid}/a2p-sms/batches
      name: restapi-v1-0-account-accountid-a2p-sms-batches
      description: REST surface for restapi-v1.0-account-accountId-a2p-sms-batches.
      operations:
      - method: POST
        name: createa2psms
        description: Send A2P SMS
        call: platform-high-volume-sms.createa2psms
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: lista2pbatches
        description: List A2P SMS Batches
        call: platform-high-volume-sms.lista2pbatches
        with:
          from: rest.from
          status: rest.status
          pageToken: rest.pageToken
          perPage: rest.perPage
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/restapi/v1-0/account/{accountid}/a2p-sms/batches/{batchid}
      name: restapi-v1-0-account-accountid-a2p-sms-batches-batchid
      description: REST surface for restapi-v1.0-account-accountId-a2p-sms-batches-batchId.
      operations:
      - method: GET
        name: reada2pbatch
        description: Get A2P SMS Batch
        call: platform-high-volume-sms.reada2pbatch
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/restapi/v1-0/account/{accountid}/a2p-sms/messages
      name: restapi-v1-0-account-accountid-a2p-sms-messages
      description: REST surface for restapi-v1.0-account-accountId-a2p-sms-messages.
      operations:
      - method: GET
        name: lista2psms
        description: List A2P SMS Messages
        call: platform-high-volume-sms.lista2psms
        with:
          view: rest.view
          phoneNumber: rest.phoneNumber
          pageToken: rest.pageToken
          perPage: rest.perPage
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/restapi/v1-0/account/{accountid}/a2p-sms/messages/{messageid}
      name: restapi-v1-0-account-accountid-a2p-sms-messages-messageid
      description: REST surface for restapi-v1.0-account-accountId-a2p-sms-messages-messageId.
      operations:
      - method: GET
        name: reada2psms
        description: Get A2P SMS
        call: platform-high-volume-sms.reada2psms
        with:
          messageId: rest.messageId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/restapi/v1-0/account/{accountid}/a2p-sms/opt-outs
      name: restapi-v1-0-account-accountid-a2p-sms-opt-outs
      description: REST surface for restapi-v1.0-account-accountId-a2p-sms-opt-outs.
      operations:
      - method: GET
        name: reada2psmsoptouts
        description: List Opted Out Numbers
        call: platform-high-volume-sms.reada2psmsoptouts
        with:
          from: rest.from
          to: rest.to
          status: rest.status
          pageToken: rest.pageToken
          perPage: rest.perPage
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/restapi/v1-0/account/{accountid}/a2p-sms/opt-outs/bulk-assign
      name: restapi-v1-0-account-accountid-a2p-sms-opt-outs-bulk-assign
      description: REST surface for restapi-v1.0-account-accountId-a2p-sms-opt-outs-bulk-assign.
      operations:
      - method: POST
        name: adda2psmsoptouts
        description: Add Opt-In/Out Numbers
        call: platform-high-volume-sms.adda2psmsoptouts
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/restapi/v1-0/account/{accountid}/a2p-sms/statuses
      name: restapi-v1-0-account-accountid-a2p-sms-statuses
      description: REST surface for restapi-v1.0-account-accountId-a2p-sms-statuses.
      operations:
      - method: GET
        name: aggregatea2psmsstatuses
        description: List A2P SMS Statuses
        call: platform-high-volume-sms.aggregatea2psmsstatuses
        with:
          phoneNumber: rest.phoneNumber
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: platform-high-volume-sms-mcp
    port: 9090
    transport: http
    description: MCP adapter for RingCentral API — High Volume SMS. One tool per consumed operation, routed inline through
      this capability's consumes block.
    tools:
    - name: send-a2p-sms
      description: Send A2P SMS
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: platform-high-volume-sms.createa2psms
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: list-a2p-sms-batches
      description: List A2P SMS Batches
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: platform-high-volume-sms.lista2pbatches
      with:
        from: tools.from
        status: tools.status
        pageToken: tools.pageToken
        perPage: tools.perPage
      outputParameters:
      - type: object
        mapping: $.
    - name: get-a2p-sms-batch
      description: Get A2P SMS Batch
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: platform-high-volume-sms.reada2pbatch
      outputParameters:
      - type: object
        mapping: $.
    - name: list-a2p-sms-messages
      description: List A2P SMS Messages
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: platform-high-volume-sms.lista2psms
      with:
        view: tools.view
        phoneNumber: tools.phoneNumber
        pageToken: tools.pageToken
        perPage: tools.perPage
      outputParameters:
      - type: object
        mapping: $.
    - name: get-a2p-sms
      description: Get A2P SMS
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: platform-high-volume-sms.reada2psms
      with:
        messageId: tools.messageId
      outputParameters:
      - type: object
        mapping: $.
    - name: list-opted-out-numbers
      description: List Opted Out Numbers
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: platform-high-volume-sms.reada2psmsoptouts
      with:
        from: tools.from
        to: tools.to
        status: tools.status
        pageToken: tools.pageToken
        perPage: tools.perPage
      outputParameters:
      - type: object
        mapping: $.
    - name: add-opt-out-numbers
      description: Add Opt-In/Out Numbers
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: platform-high-volume-sms.adda2psmsoptouts
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: list-a2p-sms-statuses
      description: List A2P SMS Statuses
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: platform-high-volume-sms.aggregatea2psmsstatuses
      with:
        phoneNumber: tools.phoneNumber
      outputParameters:
      - type: object
        mapping: $.