# Siprec subresource

## Siprec Properties

Siprec is a subresource of [Calls](/docs/voice/api/call-resource) and allows you to start a stream on a phone call and send that stream to one of the available partners via a configured [SIPREC Connector](https://console.twilio.com/us1/develop/add-ons/catalog?tags=stream_connectors). You can also stop streams started via the [\<Siprec> TwiML](/docs/voice/twiml/siprec) instruction.

Twilio operates as a Session Recording Client (SRC) for SIPREC, while Twilio's partners, such as Gridspace, operate as Session Recording Servers (SRS). Alternatively, you can provision your own SRS using the [Twilio SIPREC Connector](https://console.twilio.com/us1/develop/add-ons/catalog?tags=stream_connectors).

The SRC sends the SIPREC media to be recorded to the SRS. The SRS is responsible for storing/processing the media.

Twilio forks the audio stream of the current call and sends it in real-time to the configured connector.

There are a maximum of **four** forked streams allowed per call. By default, `<Siprec>` uses two forked streams: one for the inbound track and one for the outbound track.

Dual-Tone Multi-Frequency (DTMF) tones aren't sent to the connector.

Any communication issues encountered while streaming media to the partner will be reported in the Twilio Debugger with additional information about the failure.

```json
{"type":"object","refName":"api.v2010.account.call.siprec","modelName":"api_v2010_account_call_siprec","properties":{"sid":{"type":"string","minLength":34,"maxLength":34,"pattern":"^SR[0-9a-fA-F]{32}$","nullable":true,"description":"The SID of the Siprec resource."},"account_sid":{"type":"string","minLength":34,"maxLength":34,"pattern":"^AC[0-9a-fA-F]{32}$","nullable":true,"description":"The SID of the [Account](/docs/iam/api/account) that created this Siprec resource."},"call_sid":{"type":"string","minLength":34,"maxLength":34,"pattern":"^CA[0-9a-fA-F]{32}$","nullable":true,"description":"The SID of the [Call](/docs/voice/api/call-resource) the Siprec resource is associated with."},"name":{"type":"string","nullable":true,"description":"The user-specified name of this Siprec, if one was given when the Siprec was created. This may be used to stop the Siprec."},"status":{"type":"string","enum":["in-progress","stopped"],"description":"The status - one of `stopped`, `in-progress`","refName":"siprec_enum_status","modelName":"siprec_enum_status"},"date_updated":{"type":"string","format":"date-time-rfc-2822","nullable":true,"description":"The date and time in GMT that this resource was last updated, specified in [RFC 2822](https://www.ietf.org/rfc/rfc2822.txt) format."},"uri":{"type":"string","nullable":true,"description":"The URI of the resource, relative to `https://api.twilio.com`."}}}
```

## Configuring a SIPREC Connector \[#configure-siprec-connector]

Connectors are configured in Marketplace to ensure that the credentials needed to send the stream to a partner are stored securely. You can install and manage connectors in the [Stream Connectors Console page in Marketplace](https://console.twilio.com/us1/develop/add-ons/catalog?tags=stream_connectors) or via the [Marketplace API](/docs/marketplace/listings/api-overview-users) using the [InstalledAddOns Resource](/docs/marketplace/api/installed-add-ons).

> \[!NOTE]
>
> If you'd like to use a specific partner and don't find them in the available [Stream Connectors](https://console.twilio.com/us1/develop/add-ons/catalog?tags=stream_connectors) list, contact Twilio Support directly with details about your desired partner through the [Console](https://console.twilio.com/) or [Help Center](https://help.twilio.com) to submit a ticket.

### Twilio's SIPREC Connector

Configure your SIPREC Connector using the parameters below.

| Parameter Name           | Description                                                                                                                                                                   |
| :----------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Installed Add-On SID     | The unique identifier for your connector. It's automatically configured when you install a connector.                                                                         |
| Unique Name              | The unique name to use for your SIPREC Connector. This is the name you will use when initiating the [\<Siprec> TwiML](/docs/voice/twiml/siprec) instruction or using the API. |
| Use In                   | Specifies that the connector is available to your Voice Applications.                                                                                                         |
| Session Recording Server | The SIP URI of the server you want to stream the media to. This should be a standard SIP URI. For example, sip:name@example.com:5060.                                         |
| Credentials Header Name  | The SIP header name that your recording service uses to pass the Authorization credentials. For example, `X-Auth-Token`.                                                      |
| Credentials              | The credential token or value for Authorization to be sent to your recording service. This value will be hidden when entered in the text box.                                 |

Using Twilio's SIPREC Connector provides some additional SIP features. The **SIP URI** within the `Session Recording Server` parameter supports additional parameters: `secure` which enables Secure Real-time Transport Protocol (SRTP), as well as, `edge` which allows you to control which [Twilio edge](/docs/global-infrastructure/edge-locations) your SIPREC connections egress by.

For example, to enable SRTP and set the [edge location](/docs/global-infrastructure/edge-locations) to the ashburn edge, you would provide populate **SIP URI** below as the `Session Recording Server` address:

`sip:your-domain.com;secure=true&edge=ashburn`

## Create a Siprec

`POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Siprec.json`

| Parameter                       | Type         | Description                                                                                                                                                                                                                            |
| :------------------------------ | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AccountSid` Path               | SID\<AC>     | The SID of the [Account](/docs/iam/api/account) that created this Siprec subresource. [Not PII](/docs/glossary/what-is-personally-identifiable-information-pii#fields-marked-not-pii)                                                  |
| `CallSid` Path                  | SID\<CA>     | The SID of the [Call](/docs/voice/api/call-resource) the Siprec subresource is associated with. [Not PII](/docs/glossary/what-is-personally-identifiable-information-pii#fields-marked-not-pii)                                        |
| `Name` Optional                 | string       | The user-specified name of this Siprec subresource, if one was given when the Siprec was created. This may be used to stop the Siprec. [Not PII](/docs/glossary/what-is-personally-identifiable-information-pii#fields-marked-not-pii) |
| `ConnectorName` Optional        | string       | Unique name used when configuring the connector via Marketplace Add-on. [Not PII](/docs/glossary/what-is-personally-identifiable-information-pii#fields-marked-not-pii)                                                                |
| `Track` Optional                | string       | One of `inbound_track`, `outbound_track`, `both_tracks`. [Not PII](/docs/glossary/what-is-personally-identifiable-information-pii#fields-marked-not-pii)                                                                               |
| `StatusCallback` Optional       | uri          | Absolute URL of the status callback. [Not PII](/docs/glossary/what-is-personally-identifiable-information-pii#fields-marked-not-pii)                                                                                                   |
| `StatusCallbackMethod` Optional | http\_method | The http method for the `StatusCallback` (one of `GET`, `POST`). [Not PII](/docs/glossary/what-is-personally-identifiable-information-pii#fields-marked-not-pii)                                                                       |
| `Parameter1.Name` Optional      | string       | Parameter name [Not PII](/docs/glossary/what-is-personally-identifiable-information-pii#fields-marked-not-pii)                                                                                                                         |
| `Parameter1.Value` Optional     | string       | Parameter value [Not PII](/docs/glossary/what-is-personally-identifiable-information-pii#fields-marked-not-pii)                                                                                                                        |

### Using the SIPREC status callback

SIPREC is a protocol that enables recording and sending streams to one of the available partners via the SIPREC connector configuration. With the addition of a status callback, you can now get detailed information about the status of a SIPREC session. This feature can be used to quickly detect and troubleshoot any unexpected issues with a SIPREC session, such as an unexpected failure or interruption.

**There are two ways to use SIPREC status callback:**

From [\<Siprec>](/docs/voice/twiml/siprec#code-start-a-new-siprec-stream) TwiML, for example:

```xml
<Start>
<Siprec name="my-first-siprec" connectorName="Gridspace1" statusCallback="https://87b252436d40.ngrok.app" statusCallbackMethod="GET"/>
</Start>
```

From Start/Stop SIPREC API, for example:

```bash
curl -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN -XPOST https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Calls/CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Siprec.json --data-urlencode \
"Name=my-first-siprec" --data-urlencode "ConnectorName=Gridspace1" --data-urlencode "StatusCallback=https://XXXXXXXX.ngrok.app" --data-urlencode "StatusCallbackMethod=GET"
```

The request to the status callback contains the standard [TwiML request parameters](/docs/voice/twiml#request-parameters) and the following parameters:

| Parameter     | Description                                                                                                                                                                                         |
| :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AccountSid`  | The SID of the [Account](/docs/iam/api/account) that created this Siprec subresource. [Not PII](/docs/glossary/what-is-personally-identifiable-information-pii#fields-marked-not-pii)               |
| `CallSid`     | The SID of the [Call](/docs/voice/api/call-resource) the Siprec subresource is associated with. [Not PII](/docs/glossary/what-is-personally-identifiable-information-pii#fields-marked-not-pii)     |
| `SiprecSid`   | The SID of the Siprec subresource is associated with. [Not PII](/docs/glossary/what-is-personally-identifiable-information-pii#fields-marked-not-pii)                                               |
| `SiprecName`  | The Name of the Siprec subresource is associated with. [Not PII](/docs/glossary/what-is-personally-identifiable-information-pii#fields-marked-not-pii)                                              |
| `SiprecEvent` | The Event of the Siprec callback. Values can be: `siprec-started`, `siprec-stopped`, `siprec-error` [Not PII](/docs/glossary/what-is-personally-identifiable-information-pii#fields-marked-not-pii) |
| `Timestamp`   | The timestamp of when the Siprec callback was made. [Not PII](/docs/glossary/what-is-personally-identifiable-information-pii#fields-marked-not-pii)                                                 |

If an error has occurred, additional parameters `SiprecError`, `SiprecErrorCode` will be set as well. These params will provide context on the error that has occurred with the Siprec subresource.

## Update a Siprec

`POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Siprec/{Sid}.json`

### Path parameters

```json
[{"name":"AccountSid","in":"path","description":"The SID of the [Account](/docs/iam/api/account) that created this Siprec resource.","schema":{"type":"string","minLength":34,"maxLength":34,"pattern":"^AC[0-9a-fA-F]{32}$"},"required":true},{"name":"CallSid","in":"path","description":"The SID of the [Call](/docs/voice/api/call-resource) the Siprec resource is associated with.","schema":{"type":"string","minLength":34,"maxLength":34,"pattern":"^CA[0-9a-fA-F]{32}$"},"required":true},{"name":"Sid","in":"path","description":"The SID of the Siprec resource, or the `name` used when creating the resource","schema":{"type":"string"},"required":true}]
```

### Request body parameters

```json
{"schema":{"type":"object","title":"UpdateSiprecRequest","required":["Status"],"properties":{"Status":{"type":"string","enum":["stopped"],"refName":"siprec_enum_update_status","modelName":"siprec_enum_update_status"}}},"examples":{"updateBySid":{"value":{"lang":"json","value":"{\n  \"Status\": \"stopped\"\n}","meta":"","code":"{\n  \"Status\": \"stopped\"\n}","tokens":[["{","#C9D1D9"],"\n  ",["\"Status\"","#7EE787"],[":","#C9D1D9"]," ",["\"stopped\"","#A5D6FF"],"\n",["}","#C9D1D9"]],"annotations":[],"themeName":"github-dark","style":{"color":"#c9d1d9","background":"#0d1117"}}},"updateByName":{"value":{"lang":"json","value":"{\n  \"Status\": \"stopped\"\n}","meta":"","code":"{\n  \"Status\": \"stopped\"\n}","tokens":[["{","#C9D1D9"],"\n  ",["\"Status\"","#7EE787"],[":","#C9D1D9"]," ",["\"stopped\"","#A5D6FF"],"\n",["}","#C9D1D9"]],"annotations":[],"themeName":"github-dark","style":{"color":"#c9d1d9","background":"#0d1117"}}}},"encodingType":"application/x-www-form-urlencoded","conditionalParameterMap":{}}
```

Update a Siprec

```js
// Download the helper library from https://www.twilio.com/docs/node/install
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

// Find your Account SID and Auth Token at twilio.com/console
// and set the environment variables. See http://twil.io/secure
const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;
const client = twilio(accountSid, authToken);

async function updateSiprec() {
  const siprec = await client
    .calls("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
    .siprec("Sid")
    .update({ status: "stopped" });

  console.log(siprec.sid);
}

updateSiprec();
```

```python
# Download the helper library from https://www.twilio.com/docs/python/install
import os
from twilio.rest import Client

# Find your Account SID and Auth Token at twilio.com/console
# and set the environment variables. See http://twil.io/secure
account_sid = os.environ["TWILIO_ACCOUNT_SID"]
auth_token = os.environ["TWILIO_AUTH_TOKEN"]
client = Client(account_sid, auth_token)

siprec = (
    client.calls("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
    .siprec("Sid")
    .update(status="stopped")
)

print(siprec.sid)
```

```csharp
// Install the C# / .NET helper library from twilio.com/docs/csharp/install

using System;
using Twilio;
using Twilio.Rest.Api.V2010.Account.Call;
using System.Threading.Tasks;

class Program {
    public static async Task Main(string[] args) {
        // Find your Account SID and Auth Token at twilio.com/console
        // and set the environment variables. See http://twil.io/secure
        string accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID");
        string authToken = Environment.GetEnvironmentVariable("TWILIO_AUTH_TOKEN");

        TwilioClient.Init(accountSid, authToken);

        var siprec = await SiprecResource.UpdateAsync(
            status: SiprecResource.UpdateStatusEnum.Stopped,
            pathCallSid: "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
            pathSid: "Sid");

        Console.WriteLine(siprec.Sid);
    }
}
```

```java
// Install the Java helper library from twilio.com/docs/java/install

import com.twilio.Twilio;
import com.twilio.rest.api.v2010.account.call.Siprec;

public class Example {
    // Find your Account SID and Auth Token at twilio.com/console
    // and set the environment variables. See http://twil.io/secure
    public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID");
    public static final String AUTH_TOKEN = System.getenv("TWILIO_AUTH_TOKEN");

    public static void main(String[] args) {
        Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
        Siprec siprec =
            Siprec.updater("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "Sid", Siprec.UpdateStatus.STOPPED).update();

        System.out.println(siprec.getSid());
    }
}
```

```go
// Download the helper library from https://www.twilio.com/docs/go/install
package main

import (
	"fmt"
	"github.com/twilio/twilio-go"
	api "github.com/twilio/twilio-go/rest/api/v2010"
	"os"
)

func main() {
	// Find your Account SID and Auth Token at twilio.com/console
	// and set the environment variables. See http://twil.io/secure
	// Make sure TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN exists in your environment
	client := twilio.NewRestClient()

	params := &api.UpdateSiprecParams{}
	params.SetStatus("stopped")

	resp, err := client.Api.UpdateSiprec("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
		"Sid",
		params)
	if err != nil {
		fmt.Println(err.Error())
		os.Exit(1)
	} else {
		if resp.Sid != nil {
			fmt.Println(*resp.Sid)
		} else {
			fmt.Println(resp.Sid)
		}
	}
}
```

```php
<?php

// Update the path below to your autoload.php,
// see https://getcomposer.org/doc/01-basic-usage.md
require_once "/path/to/vendor/autoload.php";

use Twilio\Rest\Client;

// Find your Account SID and Auth Token at twilio.com/console
// and set the environment variables. See http://twil.io/secure
$sid = getenv("TWILIO_ACCOUNT_SID");
$token = getenv("TWILIO_AUTH_TOKEN");
$twilio = new Client($sid, $token);

$siprec = $twilio
    ->calls("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
    ->siprec("Sid")
    ->update(
        "stopped" // Status
    );

print $siprec->sid;
```

```ruby
# Download the helper library from https://www.twilio.com/docs/ruby/install
require 'rubygems'
require 'twilio-ruby'

# Find your Account SID and Auth Token at twilio.com/console
# and set the environment variables. See http://twil.io/secure
account_sid = ENV['TWILIO_ACCOUNT_SID']
auth_token = ENV['TWILIO_AUTH_TOKEN']
@client = Twilio::REST::Client.new(account_sid, auth_token)

siprec = @client
         .api
         .v2010
         .calls('CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa')
         .siprec('Sid')
         .update(status: 'stopped')

puts siprec.sid
```

```bash
# Install the twilio-cli from https://twil.io/cli

twilio api:core:calls:siprec:update \
   --call-sid CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
   --sid Sid \
   --status stopped
```

```bash
curl -X POST "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Siprec/Sid.json" \
--data-urlencode "Status=stopped" \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
```

```json
{
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "call_sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "sid": "Sid",
  "name": null,
  "status": "stopped",
  "date_updated": "Thu, 30 Jul 2015 20:00:00 +0000",
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Siprec/SRaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
}
```
