SIP URIs¶

Overview¶

SIP URIs are used in Enfonica products to specify endpoints and their associated parameters. For example, SIP URIs can be used in:

Cloud SIP load balancers
Incoming call configurations of phone number instances
VoiceML <Call> and <Redirect> actions
Flow Call and Load Balancer steps

SIP URIs can specify:

Where to send SIP traffic to
What Enfonica edge to send SIP traffic from
The value of the To header
Encryption options
Authentication
User-to-User information (UUI)
Custom X headers

Format¶

The general format of an Enfonica SIP URI is:

sip:[user@]host[:port][;uri-parameters][?headers]

User¶

If the userinfo of the URI is not specified, it will default to the specified or default value of the to URI header.

For example, if you are handling an incoming call to +61255501234, and you transfer the call using the URI sip:customer.example, the URI will be automatically expanded to sip:+61255501234@customer.example.

Host¶

The host can be specified as a FQDN (Fully Qualified Domain Name) or an IPv4 address. Note that IPv6 is not supported. For IDNs (International Domain Names), the ASCII format must be used.

Port¶

If the port is not specified, it will default to:

5061 if transport=tls is specified or if secure media is enabled
5060 otherwise

URI Parameters¶

URI parameters are specified in the format parameter=value and are delimited by semi-colons (;).

The following URI parameters are available.

Transport¶

The transport parameter can be set with either udp for SIP over UDP, or tls for SIP over TLS.

Enfonica will use a trusted certificate issued by a certificate authority with a wildcard domain. Enfonica will accept any certificate, including self-signed certificates, that you present.

For example:

sip:customer.example;transport=tls

Secure media¶

Secure media can be configured to protect audio using SRTP encryption. The secure parameter controls the behavior of secure media. The following options are available.

Option	Description
`true`	SRTP will be required. If the remote endpoint does not support SRTP, the call will fail. Setting this option will also set the `transport` parameter to `tls`. It is not valid to manually set the transport to a different value.
`default`	When you specify `transport=tls`, SRTP will be offered but will be optional. When you specify any other transport, SRTP will not be offered.

For example, to connect over TLS and require secure media (SRTP):

sip:customer.example;secure=true

This is equivalent to:

sip:customer.example;transport=tls;secure=true

Edge¶

To specify where Enfonica sends you traffic from, specify an Enfonica region from the available regions in the edge parameter.

If the edge is not specified, traffic will be sent from the nearest edge to where the parent call is being processed.

Note that only the sydney region is available at this time.

For example:

sip:customer.example;edge=sydney

Digest authentication¶

To specify authentication credentials, use the parameters username and password. If the INVITE is challenged, these credentials will be used, together with the challenge realm, to authenticate the call.

For example:

sip:customer.example;username=sip;password=rules

Headers¶

Headers are specified in query string format following a question mark (?), and are delimited by ampersands (&).

The following headers are available.

To header¶

The To header can be specified to override the userinfo of the URI specified in the SIP To header. The following rules apply to determine the default value.

If the SIP URI matches a defined load balancer URI or registered user:

the phone number of the parent call's to field, for PSTN calls
the userinfo of the parent call's to field, for SIP calls

Otherwise:

the userinfo of the SIP URI, if specified
the phone number of the parent call's to field, for PSTN calls
the userinfo of the parent call's to field, for SIP calls

For example:

sip:ingress@customer.example?to=0255501234

UUI (User-to-User) header¶

The complete User-to-User header can be specified. This is used to pass custom information to supported user agents. You must take care of encoding yourself as the value that you specify will be inserted into the header verbatim.

For example:

sip:customer.example?User-to-User=342342ef34%3Bencoding%3Dhex

Custom X headers¶

Custom headers can be specified prefixed with X- and will be set on the generated INVITE. Note that headers starting with X-Enfonica- are prohibited.

For example:

sip:customer.example?X-My-Custom-Header=Hello%20world

Character escaping¶

The "% HEX HEX" mechanism is used for escaping components within the URI.

Special cases¶

Sending calls to load balancers and registered users¶

When constructing a SIP URI that directs to a load balancer or a registered user, you cannot specify the following URI parameters:

port
transport
secure
edge
authentication

Specifying load balancer endpoint URIs¶

When specifying a load balancer endpoint URI within the configuration of a load balancer, you cannot specify the to URI header.