Integrate with SIPREC

Last updated 04/16/2021

For customers who would prefer to use Deepgram's real-time transcription on a traditional telephony stack rather than with WebSockets, Deepgram offers a native SIPREC integration solution.

Deepgram provides a session recording server (SRS) that listens to incoming SIPREC INVITE requests from a session recording client (SRC). Typically, the SRC is your session border controller (SBC).

To implement this, add Deepgram as an SRS in your SBC. From then on, configured calls will be sent from the SBC to Deepgram's SRS, and Deepgram will make HTTP callbacks containing the call ID and the latest real-time transcript.

Configure

The following additional products must be configured and deployed. For reference, see the following Docker Swarm configuration:

  siprec-server:
    image: deepgram/onprem-siprec-server:latest
    environment:
      # Optional: the public IP to advertise;
      # can be removed to default to a private IP.
      DEEPGRAM_PUBLIC_IP: "..."
    # Adjust the SIP ports that are exposed, if desired.
    ports:
      # Used by siprec-rtp
      - "5060:5060/udp"
      # Used by the SRC
      - "5060:5060/tcp"
      # Used by siprec-app. Not needed if running in the same network namespace.
      - "9022:9022/tcp"

  siprec-rtp:
    image: deepgram/onprem-siprec-rtp:latest
    environment:
      # [Optional] Shorthand for setting both the RTP and SIP IP addresses at once.
      DEEPGRAM_PUBLIC_IP: 1.2.3.4
      # [Optional] Set the advertised RTP IP address
      DEEPGRAM_PUBLIC_IP_RTP: 1.2.3.4
      # [Optional] Set the advertised SIP IP address
      DEEPGRAM_PUBLIC_IP_SIP: 1.2.3.4
      # [Optional] Set the RTP timeout (in seconds). Default is 0. 0 disables RTP timeouts.
      DEEPGRAM_RTP_TIMEOUT: "0"
      # [Optional] Enable and set the session timeout (in seconds). Default is disabled.
      DEEPGRAM_SESSION_TIMEOUT: "1800"
    # Adjust the RTP ports that are exposed, if desired.
    command: --rtp-range-start 21000 --rtp-range-end 21040
    ports:
      # Used by the SRC
      - "21000-21040:21000-21040/udp"
      # Used by siprec-server. Not needed if running in the same network namespace.
      - "5080:5080/udp"
      # Used by the siprec-app. Not needed if running in the same network namespace.
      - "8021:8021/tcp"

  siprec-app:
    image: deepgram/onprem-siprec-app:latest
    environment:
      # The address of the "siprec-server" instance.
      SIPREC_SERVER: "tasks.siprec-server"
      # The address of the "siprec-rtp" instance.
      RTP_SERVER: "tasks.siprec-rtp"
      # The address of the "siprec-bridge" instance.
      BRIDGE_URL: "http://tasks.siprec-bridge"
      # Optional: additional INVITE headers that should be forwarded to the bridge.
      HEADER_CAPTURE: "CSeq,User-Agent"

  siprec-bridge:
    image: deepgram/onprem-siprec-bridge:latest
    environment:
      # Change this to reflect the callback URL where a customer-run HTTP
      # server is listening for POST requests.
      CALLBACK_URL: "..."
      # Change this to point to the Speech API:
      SPEECH_API_URL: "http://tasks.api/v2"
      # The Deepgram model to use.
      DEEPGRAM_MODEL: general

    # The command arguments.
    #   --host: The interface to bind to
    #   --port: The port to bind to.
    #   --auth: Base64-encoded HTTP Basic Auth credentials for the API.
    #   --api-url: Alternative to SPEECH_API_URL environmental variable.
    #   --callback-url: Alternative to CALLBACK_URL environmental variable.
    #   --model: Alternative to DEEPGRAM_MODEL environmental variable.
    #   --args: Additional arguments, encoded as KEY=VALUE pairs. Can be specified multiple times.
    command: >-
      --host 0.0.0.0
      --port 80
      --auth HTTP_BASIC_AUTH_BASE64
      --args punctuate=true
    ports:
      # Used by siprec-rtp. Not needed if running in the same network namespace.
      - "80:80/tcp"

Usage

Assuming that your SRC has been configured to use Deepgram as an SRS, new calls will be intercepted by Deepgram and transcoded in real-time. The siprec-bridge service will make HTTP callbacks in real-time as new transcripts and other analytics are produced.

The callback format adheres to this API:

  • Method: POST
  • Endpoint: Endpoint specified in CALLBACK_URL in the sample Docker Swarm configuration (above)
  • Content-type: application/json
  • Payload: JSON-encoded message with the following format:
    {
      "call_id": CALL_ID,
      "result": RESULT
    }
    

In this example, CALL_ID is the SIP call ID, and RESULT is the standard real-time streaming response.