AI and VoIP Blog

VOIP | AI | Cloud | Kamailio | Open Source


PJSUA: Getting Started with the CLI Softphone

Engineers using telecommunications simulation equipment in lab

The PJSUA command line softphone is a versatile SIP user agent based on the PJSIP stack, ideal for VoIP engineers and enthusiasts. This guide covers the installation process on Linux and macOS, and provides a quick start on its usage. For Windows users, please refer to the detailed instructions provided in the official PJSIP documentation.

Once you can place calls from the terminal, pair it with sngrep to watch the SIP traffic, or with sipsak for quick OPTIONS checks.

Table of Contents

  1. Installing the PJSUA command line softphone on Linux
  2. Installing PJSUA on macOS
  3. Using the PJSUA command line
  4. Add custom headers to an outgoing INVITE
  5. Conclusion

Installing the PJSUA command line softphone on Linux

Install dependencies: Open a terminal and update your repositories. Then install the build packages:

apt-get update
apt install python-dev-is-python3 gcc make binutils build-essential

Get PJSIP: Download the PJSIP source code from GitHub. We will use the latest version, which is currently 2.17:

wget https://github.com/pjsip/pjproject/archive/refs/tags/2.17.tar.gz
tar xvf 2.17.tar.gz
cd pjproject-2.17/

Configure and build PJSIP: Configure the environment and build:

export CFLAGS="$CFLAGS -fPIC"
./configure && make dep && make

Install PJSUA: Copy the PJSUA binary to a directory in your PATH:

cp pjsip-apps/bin/pjsua* /usr/local/bin/pjsua

Verify installation: Check that PJSUA is installed:

pjsua --version

Installing PJSUA on macOS

On macOS, Homebrew does the whole job:

brew install pjproject

Using the PJSUA command line

Register a SIP account

Use the following command to register a SIP account:

pjsua --id="sip:USERNAME@DOMAIN" --registrar="sip:DOMAIN" --realm="*" --username="USERNAME" --password="PASSWORD"

Make a call

To make a call, press m and then press the enter key. Then enter the SIP URI in sip:number@host format and press enter again to place the call. Allow the request for microphone access to enable audio for the call.

Specify a protocol

The default protocol is UDP. To specify a different protocol, use the --use-tcp, --use-udp, or --use-tls flags. For TLS, you might need to specify the TLS certificate file and the TLS private key file if your setup requires them.

Receive a call without registration

To start PJSUA without registering to a SIP server, omit the registration parameters when launching it. You still need to specify your SIP URI with the --id option to identify yourself in calls:

pjsua --id="sip:user1@ip_address"

Make a call to this SIP URI and you will receive the call in the terminal.

Menu commands

The menu below shows how to use other features, like answering an inbound call or sending an UPDATE request.

PJSUA command line menu listing call, buddy, account, media and status commands

Sample command:

pjsua --id="sip:test@1.2.3.4:5060" --registrar="sip:1.2.3.4:5060" --realm="*" --username="test" --password="password"

You can also make a call directly without registering first:

pjsua --id="sip:USERNAME@DOMAIN" --realm="*" --username="USERNAME" --password="PASSWORD" <SIP_URI>

Sample command:

pjsua --id="sip:akash@test.com" --username="akash" --password="password" --realm="*" sip:123456@test.com

Add custom headers to an outgoing INVITE

The PJSUA command line can add a custom SIP header without a custom build. Append the header to the destination SIP URI after ? as Header=Value. PJSIP turns each URI header parameter into a real header in the outgoing INVITE.

Keep the destination URI quoted so the shell does not treat ? and & as special characters:

pjsua \
--id="sip:akashtest@example.com" \
--proxy="sip:20.224.176.13:5060" \
"sip:4912345@initial.test.com?X-Test-ID=12345"

For multiple headers, separate each header parameter with &:

"sip:4912345@initial.test.com?X-Test-ID=12345&X-Customer-ID=abc"

I tested this with PJSUA 2.17 against a local UDP listener. Both headers arrive in the INVITE. The request URI and the To header stay clean:

INVITE sip:4912345@initial.test.com SIP/2.0
To: sip:4912345@initial.test.com
Route: <sip:127.0.0.1:15070;lr>
X-Test-ID: 12345
X-Customer-ID: abc

Pro tip: URL-encode special characters in header values. For example, use %20 for a space. Then check the outgoing INVITE in the PJSUA log, or capture it with sngrep, to confirm every header is present.

To add headers from code instead, see the official guide on adding custom headers in PJSIP. For scripted SIP load and call-flow tests, SIPp is the next tool to learn.


Conclusion

The PJSUA command line offers a powerful and flexible way to work with SIP directly from your terminal. Whether you are a VoIP engineer or just starting out, PJSUA is an invaluable tool for testing, debugging, and managing SIP calls.

For more detailed information, visit the official PJSUA documentation.

Leave a Reply

Join 927 other subscribers

Akash Gupta
Senior VoIP Engineer and AI Enthusiast



Discover more from AI and VoIP Blog

Subscribe to get the latest posts sent to your email.



3 responses to “PJSUA: Getting Started with the CLI Softphone”

  1. […] For linux I prefer to build it from source – checkout my article about PJSUA to learn more – here […]

  2. […] For linux I prefer to build it from source – checkout my article about PJSUA to learn more – here […]

Leave a Reply