Telephony Integration Setup Guide¶

Last Updated: February 2026

Overview¶

This guide covers the complete setup of the VitalPBX/Asterisk telephony integration with Odoo 17 Community Edition. The integration provides:

Click-to-Dial from contact records in Odoo
Incoming call popup identifying callers from Odoo contacts
Call logging through Asterisk CDR

Architecture¶

+------------------+       ARI/AMI        +------------------+       SIP Trunk       +----------+
|   Odoo Server    | <------------------> |    VitalPBX      | <------------------> | SIP      |
|   (Port 1818)    |    Port 8088/5038    |   (Separate VM)  |                      | Provider |
+------------------+                      +------------------+                      +----------+
                                                  |
                                           SIP (Port 5060)
                                                  |
                                          +----------------+
                                          |   SIP Phones   |
                                          | (Desk/Softphone)|
                                          +----------------+

Key principle: Odoo and VitalPBX run on separate servers connected via private network. They should never share a VM.

Hardware Requirements¶

VitalPBX Server¶

Spec	Minimum	Recommended
CPU	2 cores @ 2.2 GHz	4 cores
RAM	4 GB	8 GB
Storage	50 GB SSD	100 GB SSD (if recording calls)
OS	Debian 12 (64-bit)	Debian 12 (64-bit)
Network	1 Gbps, low latency to Odoo server	Same private network/VPC as Odoo

These specs support approximately 50 extensions with 12 concurrent calls.

Network Requirements¶

Port	Protocol	Purpose	Direction
5060	UDP/TCP	SIP signaling	Phones -> VitalPBX
5061	TCP	SIP TLS (encrypted)	Phones -> VitalPBX
5038	TCP	AMI (Asterisk Manager)	Odoo -> VitalPBX
8088	TCP	ARI (Asterisk REST API)	Odoo -> VitalPBX
10000-20000	UDP	RTP media (voice)	Phones <-> VitalPBX
443	TCP	VitalPBX admin panel	Admin -> VitalPBX

Security

AMI (5038) and ARI (8088) should only be accessible from the Odoo server IP. Never expose these ports to the internet. Use VitalPBX's firewall rules to restrict access.

Software Components¶

On Odoo Server¶

Component	Version	Source
Odoo	17.0 Community	Existing
base_phone	17.0.1.0.2	OCA connector-telephony
asterisk_click2dial	17.0.1.0.0	OCA connector-telephony
Python: phonenumbers	Latest	pip
Python: requests	Latest	pip

On VitalPBX Server¶

Component	Version	Source
VitalPBX	4.5+	vitalpbx.com
Asterisk	20+ (bundled)	Included with VitalPBX

Installation Steps¶

Step 1: Install VitalPBX¶

Download from vitalpbx.com/pbx-system-download.

Option A: ISO Install (dedicated server/VM)

Boot from the VitalPBX ISO
Follow the installer (set root password, timezone, disk partitioning)
After reboot, note the IP address on the console
Open https://<IP> in a browser to complete setup

Option B: Script Install on existing Debian 12

wget https://repo.vitalpbx.com/vitalpbx/v4/vpbx4-install.sh
chmod +x vpbx4-install.sh
./vpbx4-install.sh

Step 2: Configure VitalPBX¶

Create SIP Extensions¶

Navigate to PBX > Extensions > Extensions
Click Add
Fill in:
- Extension Number: e.g., 1001
- Name: User's full name
- Technology: PJSIP
- Password: Auto-generated (note it for phone config)
Click Save, then Apply Changes
Repeat for each user

Create AMI User (for Odoo connection)¶

Navigate to Settings > PBX Settings > AMI Users
Click Add
Configure:
- AMI User: odoo
- Secret: Generate a strong password
- Deny: 0.0.0.0/0.0.0.0
- Permit: <ODOO_SERVER_IP>/255.255.255.255
- Read Permissions: call, originate, system
- Write Permissions: call, originate, system
Click Save, then Apply Changes

Enable ARI (for Odoo connection)¶

Edit /etc/asterisk/ari.conf on the VitalPBX server (or through the admin panel):

[general]
enabled=yes
pretty=yes

[odoo]
type=user
read_only=no
password=<STRONG_PASSWORD>

Restart Asterisk after changes: Settings > PBX Settings > Restart Asterisk

Firewall Rules¶

In Admin > Firewall > Rules, ensure:

Port 5038 (AMI): ACCEPT from Odoo server IP only
Port 8088 (ARI): ACCEPT from Odoo server IP only
Port 5060 (SIP): ACCEPT from your office network
Ports 10000-20000 (RTP): ACCEPT from your office network

Step 3: Install Odoo Modules¶

The modules are in the oca_telephony/ directory of the SR-Odoo repository.

# On the Odoo server, ensure the addons path includes oca_telephony
# Edit /etc/odoo17.conf:
addons_path = ...,/path/to/oca_telephony

# Install Python dependencies
/opt/odoo17/odoo17-venv/bin/pip install phonenumbers requests

# Restart Odoo
sudo systemctl restart odoo17

Then in Odoo:

Go to Apps, click Update Apps List
Search for "Asterisk connector"
Install Asterisk connector (this auto-installs Base Phone)

Step 4: Configure Odoo¶

Asterisk Server Connection¶

Go to Settings > Technical > Asterisk Servers (enable developer mode first)
Click Create
Fill in:
- Name: Production VitalPBX
- IP Address: VitalPBX server IP
- Port: 8088
- ARI Login: odoo
- ARI Password: The password from ARI config
- Dialplan Context: from-internal (VitalPBX default)
- Wait Time: 30 seconds
Click Test Connection to verify
Save

User Extension Mapping¶

For each Odoo user who will make/receive calls:

Go to Settings > Users & Companies > Users
Edit the user
In the Asterisk tab:
- Internal Number: Their extension (e.g., 1001)
- Resource Name: Same as extension (e.g., 1001)
- Asterisk Channel Type: PJSIP
- Caller ID: "User Name" <1001>
- Asterisk Server: Select the server created above

Register JS Assets (required for Odoo 17)¶

After module installation, the JS assets for the Dial button need to be manually registered. Run this in Odoo's shell or via XML-RPC:

# In Odoo shell: /opt/odoo17/odoo17-venv/bin/python3 /opt/odoo17/odoo17/odoo-bin shell -c /etc/odoo17.conf -d <DATABASE>

assets = [
    ('base_phone: on_dial_button JS', 'web.assets_backend', 'base_phone/static/src/components/on_dial_button/on_dial_button.esm.js'),
    ('base_phone: on_dial_button XML', 'web.assets_backend', 'base_phone/static/src/components/on_dial_button/on_dial_button.xml'),
    ('base_phone: phone_field JS', 'web.assets_backend', 'base_phone/static/src/components/phone_field/phone_field.esm.js'),
    ('base_phone: phone_field XML', 'web.assets_backend', 'base_phone/static/src/components/phone_field/phone_field.xml'),
    ('asterisk_click2dial: systray JS', 'web.assets_backend', 'asterisk_click2dial/static/src/components/asterisk_click2dial/asterisk_click2dial.esm.js'),
    ('asterisk_click2dial: systray XML', 'web.assets_backend', 'asterisk_click2dial/static/src/components/asterisk_click2dial/asterisk_click2dial.xml'),
    ('asterisk_click2dial: SCSS', 'web.assets_backend', 'asterisk_click2dial/static/src/scss/asterisk.scss'),
]

for name, bundle, path in assets:
    env['ir.asset'].create({'name': name, 'bundle': bundle, 'path': path})

env.cr.commit()

Then clear the browser cache (Ctrl+Shift+R) for all users.

Step 5: Configure SIP Phones¶

Each user needs a SIP phone (hardware desk phone or softphone) registered to VitalPBX.

Softphone options:

Zoiper (Windows/Mac/Linux/Mobile) - free tier available
Linphone (Windows/Mac/Linux/Mobile) - open source
MicroSIP (Windows) - open source

Phone configuration:

Setting	Value
Server/Registrar	VitalPBX IP address
Username	Extension number (e.g., `1001`)
Password	From VitalPBX extension config
Transport	UDP
Port	5060

Step 6: Configure SIP Trunk (External Calls)¶

To make/receive external calls, you need a SIP trunk provider. Configure in VitalPBX:

PBX > External > Trunks - Add your SIP provider credentials
PBX > External > Outbound Routes - Route outgoing calls through the trunk
PBX > External > Inbound Routes - Route incoming DID numbers to extensions or ring groups

Local Development Setup¶

For development/testing, use the Docker-based Asterisk setup instead of VitalPBX:

cd /path/to/SR-Odoo/asterisk-dev
docker-compose up -d

This starts Asterisk with:

PJSIP extensions: 1001 (password: test1001), 1002 (password: test1002)
ARI: Port 8088, user odoo, password odoo_ari_pass
AMI: Port 5038, user odoo, password odoo_ami_pass

Use a softphone (Twinkle, Linphone) registered to 127.0.0.1:5060 for testing.

Troubleshooting¶

Dial button not visible in Odoo¶

Check that ir.asset records were created (see Step 4)
Clear browser cache with Ctrl+Shift+R
Verify modules are installed: Settings > Apps > search "Asterisk"

Click-to-Dial fails silently¶

Check Odoo logs: sudo tail -f /var/log/odoo17/odoo17.log
Common cause: phone numbers in local format. The base_phone module has been patched to handle US local format ((865) 539-9299), but the company must have a country set (Settings > Companies > Country = United States)

"No callerID configured" error¶

Edit the user in Settings > Users > Asterisk tab
Set Resource Name to the extension number
Set Caller ID to "Name" <extension>

Connection test fails¶

Verify VitalPBX/Asterisk is running
Check firewall allows port 8088 from Odoo server
Verify ARI credentials in /etc/asterisk/ari.conf
Test manually: curl -u odoo:password http://<PBX_IP>:8088/ari/asterisk/info

Phone doesn't ring on click-to-dial¶

Verify the user's SIP phone is registered: VitalPBX admin > PBX > Extensions (check registration status)
Check that the extension number in Odoo matches VitalPBX
Check Asterisk dialplan context matches what's configured in Odoo

Environment Reference¶

Environment	Odoo URL	PBX	Database
Local Dev	localhost:1818	Docker Asterisk (localhost)	test1
Cloud Test	Not yet configured	VitalPBX (separate VM)	Not yet configured
Production	Not yet configured	VitalPBX (separate VM)	Not yet configured