Asterisk SIP channels

SIP Channel Module

The SIP Channel Module enables Asterisk to communicate via VOIP with SIP telephones and exchanges. Asterisk is able to act as

• a SIP client: This means that Asterisk registers as a client to another SIP server and receives and places calls to this server. Incoming calls are routed to an Asterisk extension.
• a SIP server: Asterisk can be configured so that SIP clients (phones, software clients) register to the Asterisk server and set up SIP sessions with the server, i.e. calls and answers incoming calls. This said, Asterisk is not a full-feature SIP server like SIP express router or OpenSER. If you are going to have thousands of SIP phones, you should use SER or OpenSER and forward calls to Asterisk for voicemail or PSTN access.
• a SIP gateway: Asterisk acts as a Media gateway between SIP, IAX, MGCP, H.323 and PSTN connections. As an example, an Asterisk server can be connected to ISDN to give your SIP clients connectivity to the switched telephony network.
• Why is Asterisk not a SIP proxy?

Notes

• Asterisk supports ENUM — see Asterisk config enum.conf.
• Asterisk support DNS SRV records, pointers to SIP proxy servers for Internet domains. See Asterisk SIP srvlookup
• When and why is Asterisk a media gateway for SIP calls? - see Asterisk SIP media path
• With a bit of tweaking, Asterisk supports SIP URL dialing.
• Asterisk supports SIP over UDP, but not over TCP.
• You can store your SIP devices in a database for dynamic configuration, see Asterisk SIP Mysql Peers

Configuring SIP Channels

Configuration of SIP Channels is done by modifying the sip.conf file. See:

• SIP Channel Configuration

Using the Dial Command with SIP Channels

Recall that the format of the Dial command is like this:

Dial(type/identifier,timeout,options,URL)

For SIP channels, the type is always SIP. The timeout, options and URL parts are explained on the Dial page.

The identifier parameter can be made up of up to three parts:

[exten@]peer[:portno]

• peer: the name of a peer to connect to. This can be one of:
  • a peer or friend defined in sip.conf
  • an IP address (e.g. 192.168.1.8)
  • a domain name (e.g. asterisk.org). For domain names, Asterisk will first look for a DNS SRV record for that domain name (If the srvlookup option is turned on). If present, this tells Asterisk which computer it should connect to. If there is no SRV record defined for the domain, then Asterisk will connect to the machine directly.
• portno: the UDP port to use. If omitted, Asterisk will use the standard SIP port, 5060.
• exten: if defined, then Asterisk will request the peer to connect us to extension exten.

Note: Only if you use a peer or friend identifier (i.e. the title of a section in sip.conf), the corresponding options for authentication etc. will be used.

Here are some examples of complete Dial commands as they might appear in your Dialplan:

exten=>s,1,Dial(SIP/ipphone);Callourpeer"ipphone"whoseconnectiondetailsareinsip.conf
exten=>s,1,Dial(SIP/joshua@ipphone);Callourpeer"ipphone",requestingextension"joshua"
exten=>s,1,Dial(SIP/[email protected]);Connecttofoo.com,requestingextension"john"
exten=>s,1,Dial(SIP/192.168.1.8:9999,20);Connectto192.168.1.8onport9999,witha20sectimeout.
exten=>s,1,Dial(SIP/[email protected]:9876);Connecttosip.comport9876,requestingextension8500.

Distinctive Ring Styles

There doesn't yet seem to be a standard for how to tell a SIP phone that you want it to ring with a distinctive ring. On SIP handsets that support distinctive ring at all, the exact method of specifying distinctive ring varies from one model to another. Often (or always?) it is by sending a SIP "Alert-info" header, but what the value of this header should be is not consistent. If you can figure out what Alert-info header Asterisk should send, then you can get Asterisk 1.0 and 1.2 to send such a header by setting the ALERT_INFO channel variable before you Dial:

exten=>s,1,SetVar(ALERT_INFO=something)
exten=>s,2,Dial(SIP/myphone)

In Asterisk 1.0 the ALERT_INFO is no longer a special variable that is inherited by the outgoing channel. Instead, a generic method of handling inheritance of variable based on prefixing the variables with an underscore "_" (or two underscores "__" for permanent inheritence) has been introduced. The following construct would be used instead of the above:

exten=>s,1,SetVar(_ALERT_INFO=something)
exten=>s,2,Dial(SIP/myphone)

As of Asterisk 1.4, setting the _ALERT_INFO or __ALERT_INFO variables no longer works. Instead, call the SIPAddHeader(Alert-Info: something) Asterisk func SIPAddHeader in your extensions.conf dialplan. By the way, already Asterisk 1.2 has supports for this new method:

exten=>s,1,SIPAddHeader(Alert-Info:something)
exten=>s,2,Dial(SIP/myphone)

To find out how to make your specific model of SIP phone do distinctive ring, try looking for reference information about this topic from:

• Asterisk Configuration Notes for Specific Phones
• Google
• Your phone user manual
• Your phone manufacturer's web site

See also: MySQL custom ringtones

VXML_URL

Phones running the SCCP (skinny) firmware have some support for pushing XML pages. If you want to test it, set the variable VXML_URL to point to a Cisco XML file on a web server.

This adds information to the SIP "To:" header, and it could be used for other purposes if there are other phones that can take extra information in this way. For example:

exten=>s,1,SetVar(VXML_URL=foobar)
exten=>s,2,Dial(SIP/john)

would result in a To: header looking something like this:

To:<sip:[email protected]:5061>;foobar

Incoming SIP Connections

When Asterisk receives an incoming SIP call, the SIP Channel Module

• first tries to find a [user] section matching the caller name (From: username),
• then tries to find a [peer] section matching the caller's IP address.
• If no matching user or peer is found, the call is sent to the context defined in the [general] section of sip.conf.

Read more about this on: Asterisk SIP user vs peer

Crossed Incoming SIP Lines

I was getting the sip context of line 1 being played over line 2 and vice-a-versa, both lines being from the same provider / from domain / host.
A quick hack is to use something similar to the following in the extensions.conf and point your incoming sip contexts to it:

[route-calls]
exten => s,1,Answer
exten => s,n,Set(cNum = ${SIP_HEADER(TO):5:11})
exten => s,n,GotoIf($[${cNum} = 12223334444]?sipLine1,s,1)
exten => s,n,GotoIf($[${cNum} = 12223335555]?sipLine2,s,1)

[sipLine1]
...code
[sipLine2]
...code

This uses the TO parameter of the sip header function to check the dialed information and returns something like <sip:[email protected]>. The substring 5:11 gives the called number to check against and jump contexts if necessary, so your line-contexts can remain distinct. FYI, the FROM parameter returns the caller information.

FreePBX users may also wish to see http://www.aussievoip.com/wiki/How+to+get+the+DID+of+a+SIP+trunk+when+the+provider+doesn%27t+send+it+%28and+why+some+incoming+SIP+calls+fail%29, which has some additional suggestions for dealing with this problem, including what to do if the provider sends a user name rather than a number in the TO parameter.

Names of Established SIP Connections

When you have an established SIP connection, its channel name will be in this format:

SIP/peer-id

peer is the identified peer and id is a random identifier to be able to uniquely identify multiple calls from a single peer.

SIP/ipphone-45ed721c—ASIPcallfrompeer"ipphone"
SIP/192.168.1.8-01fb34d6—ASIPcallfrom192.168.1.8

Note that using the ChanIsAvail command will return channel names in this format.

The Cut command can be useful for extracting the channel type from a full channel name. Let's say that the variable Foo has the value "SIP/ipphone-45ed721c":

Cut(ChannelType=Foo,/,1)

Now variable ChannelType has the value "SIP". You could use the GotoIf command to check that a channel is a SIP channel:

GotoIf($[${ChannelType} = SIP]?10)

If you wish to extract just the peer from a channel name, you might use two Cuts. If variable Foo has the value "SIP/ipphone-45ed721c", then after these steps, variable Bar will have the value "ipphone":

Cut(Bar=Foo,/,2)
Cut(Bar=Bar,-,1)

Note that this assumes you have not defined any peers in your sip.conf that have a hyphen in their name. Otherwise an attempt to Cut the peer from something like "SIP/my-name-83ee2891" would give you only "my"!

The Asterisk Console

The SIP Channel Module adds extra commands to the Asterisk CLI Console. For example,

• check the status of your own server's SIP registrations with "sip show registry";
• obtain a list of clients that have registered with your server with "sip show peers";
• after you make changes to your sip.conf file, get the SIP Channel Module to reload it with "sip reload" (will not abort active calls).