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 SIPclient: 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 SIPserver: 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 SIPgateway: 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

 

Configuring SIP Channels

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

 

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 extensionexten.

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)            ; Call our peer "ipphone" whose connection details are in sip.conf
   exten => s,1,Dial(SIP/joshua@ipphone) ; Call our peer "ipphone", requesting extension "joshua"
   exten => s,1,Dial(SIP/john@foo.com)       ; Connect to foo.com, requesting extension "john"
   exten => s,1,Dial(SIP/192.168.1.8:9999,20); Connect to 192.168.1.8 on port 9999, with a 20 sec timeout.
   exten => s,1,Dial(SIP/8500@sip.com:9876)  ; Connect to sip.com port 9876, requesting extension 8500.

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:

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:john@192.168.1.8: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:12223334444@domain.com>. 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      — A SIP call from peer "ipphone"
   SIP/192.168.1.8-01fb34d6  — A SIP call from 192.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).