AsteriskPhoneAgent: A Complete Guide to Setup and Configuration

Overview

AsteriskPhoneAgent is an integration layer that connects Asterisk-based PBX systems with agent desktop software, providing call control, presence, and CRM screen-pop features. This guide walks through system requirements, installation, configuration, security hardening, and basic troubleshooting to get a functional deployment.

1. Prerequisites

Server OS: Ubuntu 20.04 LTS or 22.04 LTS (assumed).
Asterisk: Version 18+ recommended.
Database: MySQL/MariaDB for agent state and stats (optional but recommended).
Dependencies: git, build-essential, libssl-dev, libjansson-dev, pkg-config, sox (for testing).
Network: Static IP, reachable SIP/RTP ports, firewall rules allowing SIP (5060/UDP or TLS), RTP range (e.g., 10000–20000/UDP), and agent desktop ports.
Backup: Snapshot or backup of Asterisk configuration and DB before changes.

2. Installing Asterisk and Dependencies

Update system and install build tools:

Code
sudo apt update && sudo apt upgrade -y sudo apt install -y git build-essential libssl-dev libjansson-dev pkg-config sox

Install and build Asterisk (brief summary; follow Asterisk docs for detailed build flags):

Code
cd /usr/src sudo git clone -b 18 https://gerrit.asterisk.org/asterisk asterisk cd asterisk sudo contrib/scripts/installprereq install sudo ./configure sudo make menuselect sudo make && sudo make install && sudo make samples && sudo make config

3. Installing AsteriskPhoneAgent

(If a packaged installer or repository exists, adapt accordingly. Below assumes source install.)

Clone the AsteriskPhoneAgent repository:
Code
cd /opt sudo git clone https://example.com/AsteriskPhoneAgent.git cd AsteriskPhoneAgent sudo ./install.sh

Confirm the install created service units (e.g., /etc/systemd/system/asteriskphoneagent.service) and binaries in /usr/local/bin.

4. Core Configuration Files

Important files and recommended settings:

/etc/asterisk/extensions.conf — dialplan hooks for agent CTI events.

/etc/asterisk/sip.conf or pjsip.conf — endpoints for agent desk phones and AsteriskPhoneAgent if it registers via SIP.

/etc/asterisk/asteriskphoneagent.conf (or /etc/asteriskphoneagent/*.conf) — primary agent configuration: connection details, credentials, agent states, queues integration, and event mappings.

/etc/mysql/my.cnf and AsteriskPhoneAgent DB schema — if using MySQL/MariaDB.

Example minimal snippets:

Dialplan (extensions.conf) to handle agent callbacks and originate commands:

Code
[from-internal] exten => X.,1,NoOp(Call to ${EXTEN})same => n,Queue(support,t,,,30) same => n,Hangup()

pjsip.conf for agent desktop registration (if applicable):

Code
[agent-desktop] type=endpoint transport=transport-udp context=from-internal disallow=all allow=ulaw auth=agent-desktop-auth aors=agent-desktop [agent-desktop-auth] type=auth auth_type=userpass password=strongpassword username=agent-desktop
[agent-desktop] type=aor maxcontacts=1

asteriskphoneagent.conf (example keys):

Code
[main] asterisk_host=127.0.0.1 asterisk_port=5038 ami_user=agentuser ami_pass=securepass db_host=127.0.0.1 db_user=apagent db_pass=dbpass db_name=apagentdb sip_interface=0.0.0.0 rtprange=10000-20000

5. AMI (Asterisk Manager Interface) Integration

Create an AMI user in /etc/asterisk/manager.conf:

Code
[agentuser] secret = securepass permit=127.0.0.⁄₂₅₅.255.255.255 read = system,call,log,verbose,agent,command write = system,call,agent,command

Restart Asterisk and test AMI connectivity:

Use telnet/netcat to connect to port 5038 and login with the AMI user.

Ensure AsteriskPhoneAgent can authenticate and subscribe to events.

6. Database Setup (Optional but recommended)

Install MariaDB:
Code
sudo apt install -y mariadb-server sudo mysql_secureinstallation

Create database and user:
Code
CREATE DATABASE apagentdb; CREATE USER ‘apagent’@‘localhost’ IDENTIFIED BY ‘dbpass’; GRANT ALL PRIVILEGES ON apagentdb.* TO ‘apagent’@‘localhost’; FLUSH PRIVILEGES;

Import schema provided by AsteriskPhoneAgent:
Code
mysql -u apagent -p apagentdb < /opt/AsteriskPhoneAgent/sql/schema.sql

7. Agent Desktop Setup

Configure agent clients with:

Server URL/IP and port for AsteriskPhoneAgent.

Agent credentials and extension mapping.

Softphone settings (SIP account) if integrated.

Test login, presence changes, and call control (answer, hold, transfer).

8. Queues and Agent States

Configure queues in /etc/asterisk/queues.conf:

Code
[support] music=default strategy=ringall timeout=15 wrapuptime=10 maxlen=0 member => Agent/1001

Map queue events to agent states in asteriskphoneagent.conf:

Available, Busy, WrapUp, Offline.

Validate state transitions by placing test calls and observing agent UI.

9. Security Hardening

Use TLS/SRTP for SIP and RTP where possible. Configure pjsip TLS and rtpsrtp.

Restrict AMI access by IP and use strong credentials.

Firewall: permit only required ports from trusted networks. Example UFW:
Code
sudo ufw allow from 10.0.0.0/8 to any port 5061 proto tcp sudo ufw allow 10000:20000/udp sudo ufw enable

Keep software up to date and run regular backups of configs and DB.

10. Logging, Monitoring, and Troubleshooting

Enable verbose logging in Asterisk (asterisk -rvvv) and monitor /var/log/asterisk/full.

AsteriskPhoneAgent logs typically in /var/log/asteriskphoneagent/*. Use journalctl -u asteriskphoneagent for service logs.

Common issues:

Registration failures: check credentials, NAT, transport, and firewall.

Audio one-way: check RTP range, NAT settings, and media handling (directmedia/rtp_symmetric).

AMI event gaps: ensure stable network and increase AMI event buffer if needed.

Test calls with sipp or sox for automated verification.

11. Example Deployment Checklist

Backup Asterisk configs and DB

Install Asterisk and required modules

Install AsteriskPhoneAgent and create systemd service

Configure AMI user and test connection

Create DB and import schema

Configure queues and map agents

Configure agent desktops and softphones

Apply TLS/SRTP and firewall rules

Test calls, login, and failover scenarios

Set up monitoring and scheduled backups

12. Basic Troubleshooting Commands

Asterisk CLI: sudo asterisk -rvvv

Check SIP endpoints: pjsip show endpoints / sip show peers

AMI test: nc 127.0.0.1 5038

Service logs: sudo journalctl -u asteriskphoneagent -f

13. Next Steps and Scalability

For larger deployments, separate services: dedicated AMI/agent servers, database cluster, and load balancers for agent web sockets. Use multiple Asterisk nodes with shared DB and sticky sessions or a message bus (RabbitMQ) for event distribution.

Consider HA for database (replication) and Asterisk (failover with cluster tools).

If you want, I can generate specific config files for your environment (Asterisk version, SIP driver pjsip vs chan_sip, OS version, NAT scenario).

AsteriskPhoneAgent: A Complete Guide to Setup and Configuration