VoIP / Asterisk Integration

Connect your HelpDesk to an Asterisk-based PBX system to enable click-to-call, automatic ticket creation from phone calls, and call logging.

Prerequisites

• An Asterisk PBX server (or compatible: FreePBX, Issabel, VitalPBX, etc.)
• AMI (Asterisk Manager Interface) enabled on your PBX
• A dedicated AMI user with call,originate,reporting permissions
• Network access from your HelpDesk server to the PBX on the AMI port (default: 5038)
• WebSocket (WSS) endpoint configured if using browser-based softphone

Configuration Fields

Field	Description	Example
Enable VoIP	Master toggle to activate the VoIP integration	Checked
Host	IP address or hostname of your Asterisk PBX server	192.168.1.100 or pbx.company.com
Port	AMI port on the PBX server (default: 5038)	5038
Username	AMI username configured in manager.conf on the PBX	helpdesk
Password	AMI password for the username above	your-secure-password
WSS URL	WebSocket Secure URL for browser-based SIP calls. Required for the built-in softphone.	wss://pbx.company.com:8089/ws
Context	Asterisk dial plan context for outbound calls (default: from-internal)	from-internal
Reopen Ticket	If a caller has a recently closed ticket, automatically reopen it instead of creating a new one. Set the time window in hours, or "No" to always create new tickets.	24 hours

How It Works

1. Incoming calls — When a call comes in, the system matches the caller ID to an existing contact. If found, it opens or creates a ticket automatically.
2. Click-to-call — Agents can click a phone number on any ticket or contact to initiate an outbound call through the PBX.
3. Call logging — All calls (inbound and outbound) are logged as ticket comments with duration, timestamp, and recording link (if configured on the PBX).
4. Browser softphone — If the WSS URL is configured, agents can make and receive calls directly from the browser without a separate SIP phone.

Setting Up AMI on Asterisk

Add a manager user in /etc/asterisk/manager.conf:

[helpdesk]
secret = your-secure-password
deny = 0.0.0.0/0.0.0.0
permit = YOUR_HELPDESK_SERVER_IP/255.255.255.255
read = system,call,log,agent,user,config,dtmf,reporting,cdr,dialplan
write = system,call,agent,user,config,command,reporting,originate

Then reload the manager module:

asterisk -rx "manager reload"

Setting Up WebSocket (WSS) for Browser Softphone

In /etc/asterisk/http.conf:

[general]
enabled = yes
bindaddr = 0.0.0.0
bindport = 8088
tlsenable = yes
tlsbindaddr = 0.0.0.0:8089
tlscertfile = /etc/asterisk/keys/asterisk.pem
tlsprivatekey = /etc/asterisk/keys/asterisk.key

In /etc/asterisk/pjsip.conf, add a WebSocket transport:

[transport-wss]
type = transport
protocol = wss
bind = 0.0.0.0

Troubleshooting

• Connection refused — Check firewall rules. AMI port 5038 and WSS port 8089 must be open between HelpDesk and PBX servers.
• Authentication failed — Verify username/password match manager.conf. Check the permit line allows your HelpDesk server IP.
• Calls not logging — Ensure the AMI user has read = cdr,reporting permissions.
• Browser softphone not connecting — Verify the WSS URL is correct, SSL certificate is valid, and the WebSocket transport is configured in pjsip.conf.
• Context errors — The dial plan context must exist in your Asterisk configuration. from-internal is the default on FreePBX.