Vonage SIP API

openapi: 3.2.0
info:
  title: Vonage SIP API
  version: 0.3.2
  contact:
    name: Vonage DevRel
    url: https://developer.vonage.com
    email: devlre@vonage.com
  x-metaDescription: Get started with the Vonage Video API, a powerful tool for automating video communications. Learn more in Vonage's API documentation.
  x-metaTitle: Vonage Video API for Developers | Vonage API Documentation
  description: 'Operations tagged SIP across 2 of this provider''s published API definitions: vonage-video-openapi.json, vonage-video-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://video.api.vonage.com
  description: Vonage Video
security:
- Vonage-JWT: []
tags:
- name: sip
  description: APIs relating to working with SIP calls in a video session
paths:
  /v2/project/{application_id}/dial:
    parameters:
    - $ref: '#/components/parameters/application_id'
    post:
      tags:
      - sip
      summary: Initiate an outbound SIP call
      operationId: initiate-sip-call
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: A unique ID for the SIP call.
                    example: b0a5a8c7-dc38-459f-a48d-a7f2008da853
                  connectionId:
                    type: string
                    description: The Vonage Video connection ID for the SIP call's connection in the Vonage Video session. You can use this connection ID to terminate the SIP call, using the Vonage Video REST API.
                    example: e9f8c166-6c67-440d-994a-04fb6dfed007
                  streamId:
                    type: string
                    description: The Vonage Video stream ID for the SIP call's stream in the Vonage Video session.
                    example: 482bce73-f882-40fd-8ca5-cb74ff416036
        '400':
          description: 'Bad Request

            You do not pass in a session ID or you pass in an invalid session ID.'
        '403':
          description: 'Forbidden

            The HTTP response has a 403 status code if you pass in an invalid JSON web token.

            '
        '404':
          description: 'Not Found

            The HTTP response has a 404 status code if the session does not exist.

            '
        '409':
          description: 'Conflict

            The HTTP response has a 409 status code if you attempt to start a SIP call for a session that does not use the Vonage Video Media Router.'
        '500':
          description: 'Internal Server Error

            The HTTP response has a 500 status code when the platform is temporarily unable to allocate a media server to handle the SIP call — for example, when the SIP/media infrastructure is unhealthy or at capacity. Before returning this error the platform automatically retries the request across multiple, geographically distributed media servers, so a 500 indicates a broad capacity or health issue rather than a single-server failure. The response body is a JSON object of the form `{"message": "Internal server error", "code": -1}`. This is a retryable error: clients should retry with exponential backoff.'
      description: 'To connect your SIP platform to an Vonage Video session, submit an HTTP POST request to the dial method. The audio from your end of the SIP call is added to the Vonage Video session as an audio-only stream. The Vonage Video Media Router mixes audio from other streams in the session and sends the mixed audio to your SIP endpoint.


        The call ends when your SIP server sends a `BYE` message (to terminate the call). You can also end a call using the Vonage Video REST API method to disconnect a client from a session. The Vonage Video SIP gateway automatically ends a call after 5 minutes of inactivity (5 minutes without media received). Also, as a security measure, the Vonage Video SIP gateway closes any SIP call that lasts longer than 6 hours.


        The SIP interconnect feature requires that you use an Vonage Video session that uses the Vonage Video Media Router (a session with the media mode set to routed).


        For more information, including technical details and security considerations, see the Vonage Video SIP interconnect developer guide.'
      parameters:
      - schema:
          type: string
        in: header
        name: Content-Type
        description: application/json
      requestBody:
        content:
          application/json:
            schema:
              type: object
              minProperties: 0
              properties:
                sessionId:
                  type: string
                  example: b40ef09b-3811-4726-b508-e41a0f96c68f
                  description: The Vonage Video session ID for the SIP call to join.
                token:
                  type: string
                  example: 78d335fa-323d-0114-9c3d-d6f0d48968cf
                  description: The Vonage Video token to be used for the participant being called. You can add token data to identify that the participant is on a SIP endpoint or for other identifying data, such as phone numbers. (The Vonage Video client libraries include properties for inspecting the connection data for a client connected to a session.) See the Token Creation developer guide.
                sip:
                  type: object
                  required:
                  - uri
                  properties:
                    uri:
                      type: string
                      example: sip:user@sip.partner.com;transport=tls
                      description: 'The SIP URI to be used as destination of the SIP call initiated from Vonage Video to your SIP platform.

                        If the SIP ​uri​ contains a ​transport=tls​ header, the negotiation between Vonage and the SIP endpoint will be done securely. Note that this will only apply to the negotiation itself, and not to the transmission of audio. If you also audio transmission to be encrypted, set the ​secure​ property to ​true​.'
                    from:
                      type: string
                      example: from@example.com
                      description: The number or string that will be sent to the final SIP number as the caller. It must be a string in the form of from@example.com, where from can be a string or a number. If from is set to a number (for example, "14155550101@example.com"), it will show up as the incoming number on PSTN phones. If from is undefined or set to a string (for example, "joe@example.com"), +00000000 will show up as the incoming number on PSTN phones.
                    headers:
                      type: object
                      description: This object defines custom headers to be added to the SIP ​INVITE​ request initiated from Vonage Video to your SIP platform.
                      properties:
                        headerKey:
                          type: string
                          example: some-value
                    auth:
                      type: object
                      description: This object contains the username and password to be used in the SIP INVITE​ request for HTTP digest authentication, if it is required by your SIP platform.
                      properties:
                        username:
                          type: string
                          example: username
                        password:
                          type: string
                          example: p@ssw0rd
                    secure:
                      type: boolean
                      description: A Boolean flag that indicates whether the media must be transmitted encrypted (​true​) or not (​false​, the default)
                      default: false
                    video:
                      type: boolean
                      description: A Boolean flag that indicates whether the SIP call will include video (​true​) or not (​false​, the default). With video included, the SIP client's video is included in the Vonage Video stream that is sent to the Vonage Video session. SIP video is limited to 480p at 800 kbps. The SIP client will receive a single composed video of the published streams in the Vonage Video session.
                      default: false
                    observeForceMute:
                      type: boolean
                      description: A boolean flag that indicates whether the SIP end point observes force mute moderation (true) or not (false, the default). Also, with observeForceMute set to true, the caller can press "*6" to unmute and mute the published audio. For the "*6" mute toggle to work, the SIP caller must negotiate RFC2833 DTMFs (RFC2833/RFC4733 digits). The mute toggle is not supported with SIP INFO or in-band DTMFs. A message (in English) is played to the caller when the caller mutes and unmutes, or when the SIP client is muted through a force mute action.
                      default: false
              required:
              - sessionId
              - token
              - sip
        description: ''
    servers:
    - url: https://video.api.vonage.com
      description: Vonage Video
  /v2/projects/{application_id}/session/{session_id}/play-dtmf:
    parameters:
    - $ref: '#/components/parameters/application_id'
    - $ref: '#/components/parameters/session_id'
    post:
      tags:
      - sip
      summary: Play DTMF tones into a SIP call
      operationId: play-dtmf-into-session
      responses:
        '200':
          description: OK
        '400':
          description: 'Bad Request

            One of the properties — digits or sessionId — is invalid.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 400
                  message:
                    type: string
                    example: One of the properties digits or sessionId is invalid.
        '403':
          description: 'Forbidden

            Authentication error. This can occur if you use an invalid JSON web token'
        '404':
          description: 'Not Found

            The specified session does not exist.'
      description: 'Use the play-dtmf REST API to send DTMF digits to all participants in an active Vonage Video session.


        Telephony events are negotiated over SDP and transmitted as RFC4733/RFC2833 digits to the remote endpoint.'
      parameters:
      - schema:
          type: string
        in: header
        name: Content-Type
        description: application/json
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                digits:
                  type: string
                  example: '1713'
                  description: The string of DTMF digits to send. This can include 0-9, '*', '#', and 'p'. A p indicates a pause of 500ms (if you need to add a delay in sending the digits).
              required:
              - digits
    servers:
    - url: https://video.api.vonage.com
      description: Vonage Video
  /v2/projects/{application_id}/session/{session_id}/connection/{connection_id}/play-dtmf:
    parameters:
    - $ref: '#/components/parameters/application_id'
    - $ref: '#/components/parameters/session_id'
    - $ref: '#/components/parameters/connection_id'
    post:
      tags:
      - sip
      summary: Play DMTF tones into a specific connection
      operationId: play-dtmf-into-connection
      responses:
        '200':
          description: OK
        '400':
          description: 'Bad Request

            One of the properties — digits or sessionId — is invalid.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 400
                  message:
                    type: string
                    example: One of the properties digits or sessionId is invalid.
        '403':
          description: 'Forbidden

            Authentication error. This can occur if you use an invalid JSON web token'
        '404':
          description: 'Not Found

            The specified session does not exist.'
      description: 'Use the play-dtmf REST API to send DTMF digits to a single participant in an Vonage Video call


        Telephony events are negotiated over SDP and transmitted as RFC4733/RFC2833 digits to the remote endpoint.'
      parameters:
      - schema:
          type: string
        in: header
        name: Content-Type
        description: application/json
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                digits:
                  type: string
                  example: '1713'
                  description: The string of DTMF digits to send. This can include 0-9, '*', '#', and 'p'. A p indicates a pause of 500ms (if you need to add a delay in sending the digits).
              required:
              - digits
    servers:
    - url: https://video.api.vonage.com
      description: Vonage Video
components:
  parameters:
    application_id:
      name: application_id
      in: path
      required: true
      schema:
        type: string
      description: Vonage Application UUID
    connection_id:
      name: connection_id
      in: path
      required: true
      schema:
        type: string
      description: Specific publisher connection ID
    session_id:
      name: session_id
      in: path
      required: true
      schema:
        type: string
      description: Video session ID
  securitySchemes:
    Vonage-JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-refined-from:
- vonage-video-openapi.json
- vonage-video-openapi.yml
x-errors:
  validation:
    description: The provided payload is invalid
    resolution: 'Modify your request to provide a valid payload.

      * Minimum 8 characters

      * Maximum 25 characters

      * Minimum 1 lower case character

      * Minimum 1 upper case character

      * Minimum 1 digit

      '
    link:
      text: View API reference
      url: /api/account#createAPISecret
  delete-last-secret:
    description: You can not delete your only API secret
    resolution: Add another API secret before deleting this one