Mavenir
Mavenir BYON Call Handling API (VVoIP Service)

A Mavenir-authored OpenAPI 3.0.0 definition for a Bring Your Own Number (BYON) one-to-one voice and video calling service over WebRTC, contributed by Mavenir (contact@mavenir.com, Apache 2.0) to the CAMARA API Backlog as a supporting document for the WebRTC API proposal that Mavenir co-maintains. Four operations create, retrieve, update the status of and delete a VVoIP session, exchanging SDP offers and answers. This is a contributed reference definition in a public standards repository, not a Mavenir-hosted commercial endpoint — the spec ships only a templated {apiRoot} server whose default is http://localhost:9091, and authentication is HTTP Bearer.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.0
info:
  title: Bring Your Own Number (BYON) call handling API (VVOIP Service)
  description: APIs for REST clients for 1-1 calling
  contact:
    email: contact@mavenir.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
  - url: '{apiRoot}/vvoip/{apiVersion}/{userId}'
    variables:
      apiRoot:
        description: API root
        default: http://localhost:9091
      apiVersion:
        description: Version of the VVOIP service API
        default: v1
      userId:
        description: >-
          The public identity of the user in the URI format through which client
          is trying to communicate
        default: user
tags:
  - name: OneToOneCall
    description: APIs related to 1-1 voice/video call session
paths:
  /sessions:
    post:
      tags:
        - OneToOneCall
      summary: Creates voice and/or video session
      description: Creates a voice and/or video session
      operationId: postSessions
      parameters:
        - name: transactionId
          in: header
          description: The Transaction  associated with the request
          required: true
          style: simple
          explode: false
          schema:
            type: string
        - name: clientId
          in: header
          description: The Client Id assigned by WebRTC Gateway
          required: true
          style: simple
          explode: false
          schema:
            type: string
      requestBody:
        description: Provide the information required for session creation
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VvoipSessionInformation'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VvoipSessionInformation'
              examples:
                SessionCreated:
                  $ref: '#/components/examples/exVSIResponse'
        '400':
          $ref: '#/components/responses/Generic400'
        '403':
          $ref: '#/components/responses/Generic403'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
      security:
        - BearerAuth:
            - read
            - write
  /sessions/{sessionId}:
    get:
      tags:
        - OneToOneCall
      summary: Get the vvoip session information
      description: >
        Get the VVoIP Session description based on sessionId.


        **Client shall use the resourceUrl supplied in the session creation
        response (origination) or in the invitation notification (termination)**
      operationId: getSessionDetailsById
      parameters:
        - name: transactionId
          in: header
          description: Transaction Id associated with the request
          required: true
          style: simple
          explode: false
          schema:
            type: string
        - name: clientId
          in: header
          description: The Client Id assigned by WebRTC GW
          required: true
          style: simple
          explode: false
          schema:
            type: string
        - name: sessionId
          in: path
          description: The sessionId assigned by the WebRTC GW for the vvoip session
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: A session information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VvoipSessionInformation'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/SessionNotFound404'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
      security:
        - BearerAuth:
            - read
            - write
    delete:
      tags:
        - OneToOneCall
      summary: Cancel or Terminate the vvoip session
      description: >
        Cancel a 1-1 vvoip session (as originator),

        Decline a 1-1 vvoip session (as receiver),

        Terminate a 1-1 an ongoing vvoip session


        **Client shall use the resourceUrl supplied in the session creation
        response (origination) or in the invitation notification
        (termination)**'
      operationId: deleteSessionById
      parameters:
        - name: transactionId
          in: header
          description: Transaction Id associated with the request
          required: true
          style: simple
          explode: false
          schema:
            type: string
        - name: clientId
          in: header
          description: The Client Id assigned by WebRTC GW
          required: true
          style: simple
          explode: false
          schema:
            type: string
        - name: sessionId
          in: path
          description: The sessionId assigned by the WebRTC GW for the vvoip session
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '204':
          description: Session deleted
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/SessionNotFound404'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
      security:
        - BearerAuth:
            - read
            - write
  /sessions/{sessionId}/status:
    put:
      tags:
        - OneToOneCall
      summary: Update the status of the vvoip session
      description: >
        Update the status of the vvoip session, this may include updating SDP
        media
      operationId: postSessionStatus
      parameters:
        - name: transactionId
          in: header
          description: Transaction Id associated with the request
          required: true
          style: simple
          explode: false
          schema:
            type: string
        - name: clientId
          in: header
          description: The Client Id assigned by WebRTC GW
          required: true
          style: simple
          explode: false
          schema:
            type: string
        - name: sessionId
          in: path
          description: The sessionId assigned by the WebRTC GW for the vvoip session
          required: true
          style: simple
          explode: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReceiverSessionStatus'
            examples:
              MT183:
                $ref: '#/components/examples/exMT183'
              MT180:
                $ref: '#/components/examples/exMT180'
              MT200:
                $ref: '#/components/examples/exMT200'
      responses:
        '200':
          description: Updated the session status
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/SessionNotFound404'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
      security:
        - BearerAuth:
            - read
            - write
components:
  schemas:
    VvoipSessionInformation:
      required:
        - originatorAddress
        - receiverAddress
      type: object
      properties:
        originatorAddress:
          type: string
          description: Address of the session originator
          example: tel:+911234567890
        originatorName:
          type: string
          description: Friendly name of the originator
          example: originator
        receiverAddress:
          type: string
          description: Address of the session receiver
          example: tel:+911234567891
        receiverName:
          type: string
          description: Friendly name of the receiver
          example: receiver
        status:
          $ref: '#/components/schemas/SessionStatus'
        offer:
          $ref: '#/components/schemas/WrtcsOffer'
        answer:
          $ref: '#/components/schemas/WrtcsAnswer'
        clientCorrelator:
          type: string
          description: >-
            A correlator that the client can use to tag this particular resource
            representation during a request to create a resource on the server.
            Note - This allows the client to recover from communication failures
            during resource creation and therefore avoids re-sending the message
            in such situations. In case the element is present, the WebRTC GW
            shall not alter its value, and shall provide it as part of the
            representation of this resource.
        resourceUrl:
          type: string
          description: >-
            Self referring URL. The resourceURL shall not be included in POST
            requests by the client, but must be included in the notifications
            from the WebRTC GW to client when a complete representation of the
            resource is embedded in the notification. The resourceURL must also
            be included in responses to any HTTP method that returns an entity
            body, and in PUT requests
          example: $url/{sessionId}
    SessionInvitationNotification:
      required:
        - originatorAddress
      type: object
      properties:
        originatorAddress:
          type: string
          description: Address (e.g. 'sip' URI, 'tel' URI, 'acr' URI) of the originator
          example: tel:+911234567890
        originatorName:
          type: string
          description: Friendly name of the call originator
          example: originator
        receiverAddress:
          type: string
          description: Address (e.g. 'sip' URI, 'tel' URI, 'acr' URI) of the originator
          example: tel:+911234567899
        receiverName:
          type: string
          description: Friendly name of the call receiver
          example: receiver
        offer:
          $ref: '#/components/schemas/WrtcsOffer'
        answer:
          $ref: '#/components/schemas/WrtcsAnswer'
        callObjectRef:
          type: string
          description: The reference to the call object
        serverCorrelator:
          type: string
          description: >-
            A correlator that the server instructs the client to use for end to
            end correlation. The server shall use the end to end correlator
            generated by the network to signal the client to use it for end to
            end correlation. This field can be used in the Quality-of-Experience
            (QoE) reports
    SessionStatusNotification:
      required:
        - status
      type: object
      properties:
        status:
          $ref: '#/components/schemas/SessionStatus'
        responseCode:
          type: integer
          description: >-
            Indicates corresponding SIP response code, mainly used for
            provisional responses (status set to InProgress)
        offer:
          $ref: '#/components/schemas/WrtcsOffer'
        answer:
          $ref: '#/components/schemas/WrtcsAnswer'
        receiverName:
          type: string
          description: Name of the receiver
        receiverAddress:
          type: string
          description: Address (e.g. 'sip' URI, 'tel' URI, 'acr' URI) of the receiver
        callObjectRef:
          type: string
          description: Call object reference
          format: url
        offerRequired:
          type: boolean
          description: >-
            This element shall be included and set to true, if the session
            updates are received without SDP offer. This element indicates
            clients to send the offer.
        serverCorrelator:
          type: string
          description: >-
            A correlator that the server instructs the client to use for end to
            end correlation. The server shall use the end to end correlator
            generated by the network to signal the client to use it for end to
            end correlation. This field can be used in the Quality-of-Experience
            (QoE) reports
        reason:
          type: string
          description: The description of the event that has happened within the session
        sequenceNumber:
          type: string
          description: The sequence number of the notification sent to client
    ReceiverSessionStatus:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/SessionStatus'
        responseCode:
          type: integer
          description: >
            Indicates corresponding SIP response code, mainly used for
            provisional responses (status set to “InProgress”, “Ringing”)
            Possible values are 180, 183, 200, if any other values are set, then
            the behavior is undefined or unknown. When the client sets the
            status as “Hold”, the responseCode element be set to 200. Web RTC
            gateway shall be use this to determins WebRTC GW if it's a hold
            request or response to hold notification sent earlier.
        offer:
          $ref: '#/components/schemas/WrtcsOffer'
        answer:
          $ref: '#/components/schemas/WrtcsAnswer'
        receiverName:
          type: string
          description: Name of the receiver
        receiverAddress:
          type: string
          description: Address (e.g. 'sip' URI, 'tel' URI, 'acr' URI) of the receiver
    SessionStatus:
      type: string
      enum:
        - Initial
        - InProgress
        - Ringing
        - Proceeding
        - Connected
        - Terminated
        - Hold
        - Resume
        - SessionCancelled
        - Declined
        - Failed
        - Waiting
        - NoAnswer
        - NotReachable
        - Busy
    WrtcsOffer:
      type: object
      properties:
        sdp:
          type: string
          description: >
            An inlined session description in SDP format [RFC4566].If XML syntax
            is used, the content of this element SHALL be embedded in a CDATA
            section
      description: >
        The offer, which MUST be present in a request from the application to
        the server to create a session. Note that the offer can be absent in a
        session created by the server as part of an offerless INVITE [RFC3261].
    WrtcsAnswer:
      type: object
      properties:
        sdp:
          type: string
          description: >
            An inlined session description in SDP format [RFC4566].If XML syntax
            is used, the content of this element SHALL be embedded in a CDATA
            section
      description: >
        This type represents an answer in WebRTC Signaling. This element is not
        present in case there is no answer yet, or the session invitation has
        been declined by the Terminating Participant.This element MUST NOT be
        present in a request from the application to the server to create a
        session.
    ErrorInfo:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code returned along with this error response
        code:
          type: string
          description: Code given to this error
        message:
          type: string
          description: Detailed error description
      required:
        - status
        - code
        - message
  parameters:
    hdrclientId:
      name: clientId
      in: header
      description: The Client Id assigned by WebRTC GW
      required: true
      style: simple
      explode: false
      schema:
        type: string
    hdrTransactionId:
      name: transactionId
      in: header
      description: Transaction Id associated with the request
      required: true
      style: simple
      explode: false
      schema:
        type: string
    pathParamSessionId:
      name: sessionId
      in: path
      description: The sessionId assigned by the WebRTC GW for the vvoip session
      required: true
      style: simple
      explode: false
      schema:
        type: string
  examples:
    exVSIResponse:
      value:
        originatorAddress: tel:+817085852753
        originatorName: 817085852753
        receiverAddress: tel:+817085854000
        receiverName: 817085854000
        status: Initial
        clientCorrelator: fda6e26d-e7c8-4596-870c-c083c0d39b2c
        resourceURL: >-
          $url/sessions/0AEE1B58BAEEDA3EABA42B32EBB3DFE0DEAD3F90AE0CEB9EEB0C0F703E199FC00E7C6E648F50EE885FF0CE6C7E1CEE795EDD
    exMT183:
      value:
        receiverSessionStatus:
          status: InProgress
          answer:
            sdp: "v=0\r\no=- 8066321617929821805 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 42988 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:2448:7a05:9b11:66f2:c9e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:1645903805 1 udp 2122262783 2001:e0:410:2448:7a05:9b11:66f2:c9e 42988 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:4eKp\r\na=ice-pwd:D4sF5Pv9vx9ggaqxBlHbAFMx\r\na=ice-options:trickle renomination\r\na=mid:audio\r\na=extmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\r\na=sendrecv\r\na=rtcp-mux\r\na=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:Xm3YciqVIWFNSwy19e9MvfZ2YOdAZil7oT/tHjdf\r\na=rtpmap:102 AMR-WB/16000\r\na=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2\r\na=rtpmap:113 telephone-event/16000\r\n"
          responseCode: '183'
    exMT180:
      value:
        receiverSessionStatus:
          status: Ringing
          responseCode: '180'
    exMT200:
      value:
        receiverSessionStatus:
          status: Connected
          answer:
            sdp: "v=0\r\no=- 4576312012535546667 4 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 47510 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:243a:a344:cee7:7b39:bb1e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:3108871805 1 udp 2122262783 2001:e0:410:243a:a344:cee7:7b39:bb1e 47510 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:47Nx\r\na=ice-pwd:ln3CttOSkObcQ7A0tYO1LXqy\r\na=ice-options:trickle renomination\r\na=mid:audio\r\na=extmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\r\na=sendrecv\r\na=rtcp-mux\r\na=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:ruAnBNYnTJqDVZAIJV59VpQ5DxGI6tMX9h9kkHSz\r\na=rtpmap:102 AMR-WB/16000\r\na=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2\r\na=rtpmap:113 telephone-event/16000\r\na=ptime:20\r\n"
          responseCode: '200'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
  responses:
    Generic400:
      description: Invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 400
            code: INVALID_ARGUMENT
            message: Schema validation failed at  ...
    Generic401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 401
            code: UNAUTHENTICATED
            message: 'Authorization failed: ...'
    Generic403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 403
            code: PERMISSION_DENIED
            message: 'Operation not allowed: ...'
    SessionNotFound404:
      description: Session not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 404
            code: NOT_FOUND
            message: Session Id does not exist
    Generic500:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 500
            code: INTERNAL
            message: 'Internal server error: ...'
    Generic501:
      description: Not Implemented
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 501
            code: NOT_IMPLEMENTED
            message: Service not implemented for the specified user device
    Generic503:
      description: Service unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 503
            code: UNAVAILABLE
            message: Service unavailable
Mavenir BYON Call Handling API (VVoIP Service)

Documentation

Specifications

Other Resources

OpenAPI Specification
