Telnyx SIPREC server (SRS) Configuration Guide

SIPREC (Session Initiation Protocol Recording) is a standardized mechanism for recording VoIP calls. A SIPREC server, also known as a Session Recording Server (SRS), captures and stores these communications for compliance, quality assurance, and other purposes.

This guide provides instructions for setting up and configuring a SIPREC server using Telnyx's Voice API connection.

1. Log to the Telnyx portal.
2. Navigate to the Voice -> Programmable Voice -> Voice API section.
3. Create a new Voice API Application by clicking the "Add New Application" button.
4. Configure the application settings as required for your use case. Ensure to provide a meaningful name and description for easy identification.

1. Within your new Voice API Application, locate the section for Inbound Settings.
2. Assign an inbound SIP subdomain to your application. This subdomain will route incoming SIP traffic to your SIPREC server. Example subdomain format: yourcompany.sip.telnyx.com
3. Save the changes to apply the new configuration.

With your Voice API Application and SIP subdomain set up, the next step is configuring your SIPREC Client (SRC) to interact with Telnyx SIPREC Server (SRS).

Please configure your SIPREC Client to use the following Session Recording Server URI:

sip:username@siprec.telnyx.com;secure=true?X-DestHost=yourcompany.sip.telnyx.com

Where:

• username: any SIP username can be used, this information will be dropped
• siprec.telnyx.com: is the Telnyx SIPREC server (SRS) domain
• X-DestHost: contains the SIP subdomain of your Voice API application from step #2

When the siprec session starts, two webhooks, one for each of the SIP calls of the media stream will be sent:

{
  "created_at": "2024-09-17T12:16:39.365600Z",
  "event_type": "call.initiated",
  "payload": {
    "call_control_id": "v3:ehsopsWMfki2clglbX0x4zeJoD1lV52zwLnw7rDJq_-kJoSnZcr0LQ",
    "call_leg_id": "b0f1c476-74ee-11ef-865a-02420aef3e20",
    "call_session_id": "b0f1c8fe-74ee-11ef-8704-02420aef3e20",
    "caller_id_name": "Outbound Call",
    "client_state": null,
    "connection_id": "1684641123236054244",
    "custom_headers": [
      {
        "name": "X-DestHost",
        "value": "rafal.sip.telnyx.com"
      },
      {
        "name": "X-Label",
        "value": "outbound"
      },
      {
        "name": "X-ParticipantID",
        "value": "F7yzLJtvXnTLaZflfmhkwpR5"
      },
      {
        "name": "X-SIPREC-SessionID",
        "value": "1772ce22-99ca-476a-b58f-1b848702e2ce"
      },
      {
        "name": "X-StreamID",
        "value": "QxjNUZblCzXqwKCTQpsm4Ok3"
      },
      {
        "name": "X-metadata-xml",
        "value": "PD94bWwgdmVyc2...."
      }
    ],
    "direction": "incoming",
    "from": "+48662211095",
    "occurred_at": "2024-09-17T12:16:39.123397Z",
    "offered_codecs": "PCMU,PCMA,G729",
    "start_time": "2024-09-17T12:16:39.123397Z",
    "state": "parked",
    "to": "+48662211095"
  },
  "record_type": "event",
  "webhook_id": "93415bbe-f7c3-4053-8b55-f4a1820d8dbf"
}

As the next step, the call can be answered and recording can be start using the following Voice API commands:

curl -L 'https://api.telnyx.com/v2/calls/v3:ehsopsWMfki2clglbX0x4zeJoD1lV52zwLnw7rDJq_-kJoSnZcr0LQ/actions/answer' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{}'

curl -L 'https://api.telnyx.com/v2/calls/v3:ehsopsWMfki2clglbX0x4zeJoD1lV52zwLnw7rDJq_-kJoSnZcr0LQ/actions/record_start' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{}'

By following this guide, you should have been able to successfully set up and configure your SIPREC client and server sides.

This is a typical SIPREC call flow:

1. A call is established on the user’s SBC (which has SIPREC SRC capabilities) with RTP streams A and B
2. The SIPREC SRC initiates a SIPREC call towards the Telnyx SIPREC SRS (siprec.telnyx.com), with two RTP streams (A and B)
3. The Telnyx SRS initiates two SIP calls towards sip.telnyx.com, one for each RTP stream, and each one with a:sendonly, indicating that RTP is only sent and not received.
4. Telnyx sends two call.initiated webhooks to the Voice API application URL, one for each of the SIP calls, including the call_control_id and the metadata from the original SIPREC call (more on this in the next section).
5. The call_control_id is used to issue the Voice API commands to answer and record both calls.

Telnyx will pass the metadata that’s included by the SIPREC client on the original SIPREC INVITE message as custom SIP headers on the SIP calls, and each of these will trigger a webhook that contains all of the SIP custom headers.

Webhook variables with SIPREC metadata from the INVITE message received by the SIPREC SRS:

• to: the content of the SIP URI
• SIP Custom headers: any SIP custom headers will be included in the webhook
• SIPREC XML default metadata: These variables are extracted from the XML metadata and included in the webhook
  • DataMode
  • ParticipantID
  • NameID-AOR
  • Associate-Time
  • StreamID
  • Label
• SIPREC XML custom metadata: any custom variables will also be extracted from the XML metadata and included in the webhook