Subscribe to News
Embedding of asterisk into egroupware
Author : Jbuenol
From TechnologicalWiki
 This article doesn't belong to any category. Each article must belong at least some the next categories :
- OpenSource - HowTo - Mobile - Project - ProjectSection - UnifiedCommunications - OSAmI -
Please add a valid category to the end of the article. |
Contents |
Goal of this article
This article pretends to show you Asterisk's principles, and, how it works. So, you will can to communicate and manage Asterisk with other applications created by yourself.
eGroupware is a complete set of collaborative applications for SMEs. It is based on Open Source and written in php. So, we are going to use eGroupware as a third-party application to embed Asterisk into it. The first step is to install eGroupware software. You can do this download it from [1] or installing EBox Platform software which includes to eGroupware software.
When you finish reading this article you will know :
- How to use Asterisk Manager API to access from other application.
- How to create a simple application using eGroupware to embed the Asterisk use into the eGroupware software ( php code ).
- How to retrieve Asterisk user data.
- How to modify Asterisk behaviour when an event (call, ...) occurs.
[edit] Installation
We are going to suppose an eBox distribution has been installed ( 2nd option ). You must install eBox Platform ( At least, office & communication profiles ), and then, eGroupware will be installed and configured properly.
[edit] Asterisk Manager API
We are going to suppose asterisk is properly configured (users, extensions, ... ).
The Asterisk Manager Interface (AMI) allows a client program to connect to an Asterisk instance and issue commands or read events over a TCP/IP stream. Integrators will find this particularly useful when trying to track the state of a telephony client inside Asterisk, and directing that client based on custom (and possibly dynamic) rules.
A simple "key: value" line-based protocol is utilized for communication between the connecting client and the Asterisk PBX. Lines are terminated using CR/LF. For the sake of discussion below, we will use the term "packet" to describe a set of "key: value" lines that are terminated by an extra CR/LF.
[edit] Packet Types
The type of a packet is determined by the existence of one of the following keys:
Action: A packet sent by the connected client to Asterisk, requesting a particular Action be performed. There are a finite (but extendable) set of actions available to the client, determined by the modules presently loaded in the Asterisk engine. Only one action may be outstanding at a time. The Action packet contains the name of the operation to be performed as well as all required parameters.
Response: the response sent by Asterisk to the last action sent by the client.
Event: data pertaining to an event generated from within the Asterisk core or an extension module.
[edit] Opening a Manager Session and Authenticating as a User
In order to access the Asterisk Manager functionality a user needs to establish a session by opening a TCP/IP connection to the listening port (usually 5038) of the Asterisk instance and logging into the manager using the 'Login' action. This requires a previously established user account on the Asterisk server. User accounts are configured in /etc/asterisk/manager.conf. A user account consists of a set of permitted IP hosts, an authentication secret (password), and a list of granted permissions.
There is a finite set of permissions, each may be granted with either "read", "write", or "read/write" granularity. If a client is granted the ability to read a given class, Asterisk will send it events of that class. If a client is granted the ability to write a given class, it may send actions of that class.
To login and authenticate to the manager, you must send a "Login" action, with your user name and secret (password) as parameters. Here is an example:
Action: login Username: admin Secret: god
If you do not need to subscribe to events being generated by Asterisk, you may also include the "Events: off" parameter, which will prevent event packets being sent to your connection. This is the equivalent of calling the "Events" action. Example:
Action: login Username: admin Secret: god Events: off
That's a mold-breaekr. Great thinking!
[edit] Astmanproxy
Astmanproxy is a proxy application to manage AMI connections from other applications :
- There is only one persistent connection to Asterisk. - A more secure TCP/IP Interface ( no-root ) - IN/OUT Filter (requests - responses) - Less connections and network load for Asterisk.
Use of a proxy for the AMI interface is useful as a communication with multiple servers simultaneously and secure.
Astmanproxy has the next benefits:
- Multiple IN/OUT formats (HTTP, XML, CSV y standard input) - SSL Support - API for adding new modules that support other IN/OUT formats. - Communication capability with multiple Asterisk servers. - IN/OUT specific formats for each client. - It is written in C/pthreads language to be faster and robust.
You can use Astmanproxy as a base for applications based on web, sending them data through HTTP POST or HTTP GET and receiving a XML response, or using a .NET development to monitoring Asterisk.
Click here to see how to install & configure Astmanproxy in Linux ( eBox 1.4 - Ubuntu server 8.04 LTS ).
Now, you can manage Asterisk using Astmanproxy ( port 1234 ).
1 - Your application does an http request to Astmanproxy.
2 - Astmanproxy returns a XML (in our case,format can be modified )response with the response.
Example :
Request : http://<Astmanproxy-server-IP>:1234/?Action=ListCommands&ActionID=12345
This request can be done using the usual ways ( curl,soap, ... ).
[edit] Creating the user interface
We are going to create a little application for eGroupware to create an interface to communicate with Asterisk. To create an eGroupware application you can visit The code corner of egroupware official site
[edit] How to retrieve data from Asterisk
In a usual way, users,extensions,meeting rooms in asterisk are registered in a set of *.conf files (sip.conf, extensions.conf, meetme.conf, ...) into the Asterisk folders.
Example : ( extensions.conf fragment )
...
exten => _X!,1,Dial(SIP/${EXTEN},15,Ttm) ;
exten => _X!,102,Voicemail(${EXTEN}@default) ;
exten => _X!,103,Hangup ;
;This lines represent a secuence of actions made for Asterisk when any extension is called ( _X! : This pattern indicates ANY EXTENSION )
...
In this case, data is stored into LDAP Directory ( eBox installation use this asterisk configuration (LDAP) ), and then, you can get data from LDAP with PHP using the php5_ldap module.
Example : ( php code )
...
if ($this->ds) {
ldap_set_option($dp, LDAP_OPT_PROTOCOL_VERSION, 3);
$r=ldap_bind($this->ds); // this is an "anonymous" bind, typically
// read-only access
// Search surname entry
$sr=ldap_search($this->ds, 'Base DN', 'Filter' , array('field1','field2',...));
// Example --> DN Base : dc=example Filter : objectClass=* field1 : cn , field2 : uid , ...
$info = ldap_get_entries($this->ds, $sr);
}
...
Base DN can be checked accessing https://<IP>/ebox/Users/View/LdapInfoat your server.
The /etc/asterisk/res_ldap.conf file configures the behavior of Asterisk's LDAP backend.
[edit] Getting extensions / users
This section is typed following the steps for an eBox installation. eBox uses a LDAP for data. Each user allow to the "AsteriskSIPUser" class. So, you can retrieve these data filtering by objectClass=AsteriskSIPUser :
Filter : objectClass=AsteriskSIPUser
Example : ( php code )
...
if ($this->ds) {
ldap_set_option($dp, LDAP_OPT_PROTOCOL_VERSION, 3);
$r=ldap_bind($this->ds); // this is an "anonymous" bind, typically
// read-only access
// Search surname entry
$sr=ldap_search($this->ds, ... , 'objectClass=AsteriskSIPUser' , array ('cn', 'AstAccountCallerID' ,'uid') );
// 'cn' : full name 'AstAccountCallerID' ( callerid ) : Asterisk Account 'uid' : user
$info = ldap_get_entries($this->ds, $sr);
}
...
[edit] Managing voicemail
[edit] Retrieving info messages
In Asterisk, each user has a personal voicemail. The voicemail data is stored in :
/var/spool/asterisk/voicemail/users/<extension>/<voicemail_folder>
<extension> : Extension number. <voicemail_folder> : INBOX , Old ( messages ) , Urgent ( messages )
All info of messages is stored into msg<XXXX>.txt
Example :
extension : 1000 folder : /var/spool/asterisk/voicemail/users/1000/INBOX message 1 : msg0000 data message : msg0000.txt audio files : msg0000.wav, msg0000.WAV, msg0000.gsm
msg0000.txt file :
; ; Message Information file ; [message] origmailbox=1000 context=default macrocontext= exten=1000 priority=3 callerchan=SIP/User-00000004 callerid=1001 origdate=Thu Sep 9 10:51:11 AM UTC 2010 origtime=1284029471 category= flag= duration=19
Last one to uitlzie this is a rotten egg!
Way to go on this essay, hleped a ton.
