PortaPhone configuration

Link copied to clipboard

Preparation steps

Link copied to clipboard

Before proceeding with the PortaPhone module configuration and deployment, perform the following steps:

  1. Configure a domain
  2. Obtain TLS certificates for the domain (optional)

Configure subdomains

Link copied to clipboard

Configure the following subdomains under your main domain:

  • A “core” domain – the address that the PortaPhone mobile and web applications use to connect to their backend. End users do not see it.
  • A “dialer” domain – the PortaPhone web URL that you provide to your end users. This domain is not required if you use only the PortaPhone mobile application.

If you plan to enable log collection through a logs proxy, configure a third subdomain:

  • A “logs proxy” domain – used to receive logs.

For example, if your main domain is company.com, you can configure the following subdomains: dialer.company.com, core.company.com, and logs.company.com (any names can be used).

Configure DNS for the domains so that they point to the Add-on Mart cluster in the region closest to your PortaSwitch. Use one of the following options:

  • A CNAME record pointing to the cluster hostname.
  • An A record pointing to the cluster IP address.

For cluster hostnames and IP addresses by region, see Add-on Mart service addresses by region.

Obtain TLS certificates for domains (optional)

Link copied to clipboard

TLS certificates can be generated automatically by PortaOne using Let’s Encrypt certification authority (CA). If you choose this option, you can skip this chapter.

NOTE: If you configured Certification Authority Authorization (CAA) DNS record for your main domain to permit issuing certificates only via a specific CA, then you need to additionally permit issuing certificates via Let’s Encrypt CA for your subdomains. Add the following CAA records to the DNS configuration for the “dialer” and “core” subdomains:

  • dialer.company.com IN CAA 0 issue “letsencrypt.org”
  • core.company.com IN CAA 0 issue “letsencrypt.org”

Optionally, you can contact your trusted CA to order a TLS certificate for your domains. It can be a wildcard certificate, which is issued for the main domain and covers any of its subdomains, or a certificate issued for the subdomains configured above (e.g., dialer.company.com, core.company.com, and logs.company.com). After you receive the TLS certificate and the private RSA key file from the CA, you can upload them in the PortaPhone Configuration UI.

Configuration overview

Link copied to clipboard
  1. Configuration in PortaBilling
  2. Configuration in Add-on Mart
  3. Deployment
  4. Make test calls

1. Configuration in PortaBilling

Link copied to clipboard

1.1 Create an API user with an API token

Link copied to clipboard

Create a new API user in PortaBilling for PortaPhone. Use the PortaBilling environment that you associate with your PortaPhone application. Later, in the Configuration UI, you specify this user’s login and API token in the Admin login and Admin token fields.

  1. Log in to the PortaBilling web interface as a Root admin.
  2. Navigate to My company > Users.
  3. Click + Add and fill in the user details:
    • Login – type the username PortaPhone will use to connect to the PortaBilling API.
    • Password – define a strong password for this user.
    • Email – type the email address of the admin, which will be used for receiving alerts and password recoveries.
    • Role – select Root for this user.
    • Activation – set the activation date for the user.

      Create API user for PortaPhone.

  4. Click Save&Edit.
  5. On the Edit user panel, click Web interface and enable the API token access option.

    Enable API access token for API PortaPhone user.

  6. Click Save.

When filling in the Configuration UI later, use this user’s login and the generated token to connect to the PortaBilling API.

1.2 Check the cloud PBX configuration

Link copied to clipboard

Log in to the PortaBilling admin web interface and check that the products, PBX customers, accounts, and extensions are all configured. Refer to the Cloud PBX services handbook for the configuration steps. You can create test customers and accounts first.

For PortaPhone, make sure that:

  • Email addresses are specified for the PBX accounts. PortaPhone sends the verification code to the account’s email address. To add an email address, open a PBX account and enter it on the General info panel (Basic info tab).

    PortaPhone account email address.

  • Web interface credentials are defined for the PBX customers and accounts (Web interface settings).
  • At least one customer account has an extension.

2. Configuration in Add-on Mart

Link copied to clipboard

2.1 Grant your system access to the Add-on Mart services

Link copied to clipboard
You need to set up the connection between your PortaSwitch and Add-on Mart only once. If you have already completed this step when activating other modules, skip it.

To grant your system access to the Add-on Mart services:

  1. In the Add-on Mart management portal, open the My modules page and copy the credentials.

    Copy PortaSwitch credentials.

  2. In the PortaBilling web interface, navigate to My company > Company info > Add-on Mart, and enter these credentials.

    Paste PortaSwitch credentials.

2.2 Fill in the Configuration UI settings

Link copied to clipboard

In the Add-on Mart management portal, locate your PortaPhone subscription and click Configure.

PortaPhone configure option.

General settings

Link copied to clipboard

Instance location – to minimize latency, select the cloud data center closest to your PortaSwitch for the module deployment.

PortaPhone version to deploy – choose a module version. The following options are available:

  • Deploy the latest (recommended) – select if you want to deploy the latest version.
  • Select from the full list – select if you want to choose a specific PortaPhone version.

    PortaPone General settings.

Company info

Link copied to clipboard

Company name – specify the company name shown as “by Company name” at the bottom of the PortaPhone web sign-in page. If a Company URL is set, the name links to it.

Company name on sign-up page.

Company URL – specify the link to your company website that opens when a user clicks the Company name.

PortaPhone company info.

App info

Link copied to clipboard

App name – specify the name of your application shown in the header of the application menu. It appears on both the web interface and mobile application.

PortaPhone app name.

App subname – if your application name consists of two parts that you want displayed in different fonts (e.g., MyCompany Softphone), specify the second part here. It appears next to the application name in a different font.

Custom colors – to change the interface colors, select the checkbox and choose a color for each element.

Favicon – click to upload an .ico image (32×32) to use as the favicon for the PortaPhone web page.

Company logo – click to upload an image to use as the company logo for the PortaPhone web and mobile applications. Define the logo’s size.

PortaPhone company logo.

Company logo (mini) – click to upload an image to use as the company mini logo for the PortaPhone web application. Define the mini logo’s size.

PortaPhone company mini logo.

Login page logo – click to upload an image to use as the logo on the PortaPhone web login page. Define the logo’s size and position on the page.

PortaPhone App info.

Connection to VoIP system

Link copied to clipboard

VoIP system connection type – select the platform PortaPhone connects to.

  • PortaSwitch – select this option to connect PortaPhone to PortaSwitch.
  • Externally hosted BSS adaptor – select this option to connect PortaPhone to a VoIP system or PBX other than PortaSwitch using a custom adapter hosted outside PortaSwitch.

Admin URL – specify the URL of the PortaBilling administrator interface: https://<your PortaSwitch domain>:<optional port>. For example, https://demo.portaone.com:443.

Admin login – specify the login of the admin user you created in Configuration in PortaBilling. PortaPhone uses this login to connect to the PortaBilling API.

Admin token – specify the user token generated in the Configuration in the PortaBilling preparation step.

Account URL – specify the URL of the PortaSwitch account self-care interface: https://<your PortaSwitch domain>:<account_realm_port>. For example, https://demo.portaone.com:8445.

SIP Host:Port – specify the IP address/domain name of the SIP node with port: <domain name/IP address>:<port>. For example, 1.1.1.1:5060.

Verify HTTPS certificate – select this checkbox to enable HTTPS certificate verification for the PortaSwitch API.

Max HTTP connections to PortaSwitch API – specify the maximum number of concurrent HTTP connections that PortaPhone keeps open to the PortaSwitch API. Increase this value if PortaSwitch handles a high volume of requests. Decrease it to limit the load PortaPhone places on PortaSwitch.

Max keep-alive HTTP connections to PortaSwitch API – specify the number of idle HTTP connections that PortaPhone keeps open for reuse with the PortaSwitch API. This value must be less than or equal to Max HTTP connections to PortaSwitch API.

PortaSwitch API request timeout (seconds) – specify how many seconds PortaPhone waits for a response from the PortaSwitch API before the request times out. This frees the connection for other requests when PortaSwitch responds slowly.

Enable disaster-recovery failover (standby site) – select this checkbox to let PortaPhone automatically switch to a standby PortaSwitch site if the main site becomes unavailable. This applies to site-redundant PortaSwitch. When enabled, specify the standby site’s Admin and Account API URLs below. PortaPhone switches back to the main site once it returns to normal mode.

PortaPhone Connection to VoIP system.

The following options apply only when Enable disaster-recovery failover is enabled:
Link copied to clipboard

Admin URL (standby site) – specify the URL of the admin interface on the secondary PortaSwitch site, e.g., https://dr.owl.com:443.

Account URL (standby site) – specify the Account realm REST API URL of the standby PortaSwitch site, e.g., https://dr.abc.com:8445.

DR main-site re-check interval (seconds) – specify how often PortaPhone checks whether the main PortaSwitch site has recovered once PortaPhone has switched to the secondary site.

DR switch-back threshold (consecutive normal checks) – specify how many checks in a row must show the main PortaSwitch site in normal mode before PortaPhone switches traffic back to it. A higher value keeps PortaPhone from switching back and forth while the main site is still unstable.

PortaSwitch sign-in Credentials – select which system credentials end users will use to sign in to PortaPhone:

  • self-care – customers sign in with the same login and password they use for the account self-care web interface.
  • sip – customers sign in with their SIP registration credentials (the account ID and service password).

PortaSwitch contacts selecting – select which PortaBilling data populates the contact list in PortaPhone:

  • accounts – shows the customer’s accounts.
  • extensions – shows the customer’s PBX extensions.
  • phonebook – shows entries from the customer’s phonebook.
  • phone directory – shows entries from a phone directory.

Extension types – select which extension types appear in the contact list. Applies only when PortaSwitch contacts selecting is set to Extensions.

Filter contacts without extension – select this checkbox to exclude accounts without an extension from the contact list.

Hide balance in user info – select this checkbox to hide the account’s own balance from the account information shown in PortaPhone.

Self-config portal URL – specify the URL of a portal you want to add as a link in the PortaPhone application. When set, a button that opens this portal appears in the PortaPhone mobile application, and PortaPhone signs the customer in to the portal automatically, using their current session.

Customer IDs for phonebook contact enrichment – specify which customers’ accounts PortaPhone searches for matching phone numbers. When it finds a match, PortaPhone adds the account’s company name (defined in the Address section), email address, extension, additional phone numbers, and SIP registration status to the corresponding phonebook or phone directory entry. Separate multiple IDs with a semicolon, e.g., 1;2;3. Applies only when PortaSwitch contacts selecting is set to Phonebook or Phone directory.

Custom Contacts – specify static contacts to add to the contact list, in addition to the contacts PortaPhone retrieves from PortaSwitch (e.g., a support line or an IVR number). Each entry is a JSON object with name and number fields, for example: {\”name\”: \”Greeting\”, \”number\”: \”123\”};{\”name\”: \”Customer Support\”, \”number\”: \”456789\”}. Separate multiple entries with a semicolon.

Allowed Add-Ons – specify the names of one or more account add-ons. Only accounts assigned at least one of the listed add-ons can sign in to PortaPhone. Leave this field empty to allow any account to sign in. Separate multiple add-ons with a semicolon.

Use WebRTC IP for RTP – by default, PortaPhone sends call media through the Add-on Mart NAT gateway. Enable this option to send media from the WebRTC IP address instead. Use this in network setups where routing media through the NAT gateway causes call quality or connectivity issues.

Use Firestore for OTP storage – select this checkbox to store one-time passwords (OTPs), the verification codes PortaPhone sends to customers, in Google Cloud Firestore instead of locally. Select this checkbox if your deployment runs more than one copy of the PortaPhone backend (e.g., for load balancing or failover). Each copy has its own local storage, so a code generated on one copy cannot be verified on another.

Google Cloud Service Account JSON – applies only when Use Firestore for OTP storage is selected. Upload the credentials key file for the Google Cloud service account PortaPhone uses to authenticate to Google Cloud Firestore. This is not required if PortaPhone runs on Google Cloud Platform (GCP) with Workload Identity or an instance-attached service account, since those let PortaPhone authenticate automatically without a key file.

The following options are available when Externally hosted BSS adaptor is selected for VoIP system connection type.
Link copied to clipboard

Custom BSS adapter URL – specify the base URL of your externally hosted BSS adapter: the scheme and host, plus the port if it is not standard, for example https://adapter.example.com. Do not add a path such as /api/v1. PortaPhone adds the adapter API paths itself. PortaPhone sends requests to this URL for user authentication and SIP data retrieval.

Connection to SMS provider

Link copied to clipboard

Enable SMS functionality – select this checkbox to enable sending SMS messages from PortaPhone. All other options in this section are available only when this is enabled.

SMS provider connection type – select how PortaPhone sends SMS messages.

  • SIP Simple – sends the message from the sender’s PortaPhone application over the application’s own SIP connection, so no external SMS provider is needed. PortaSwitch delivers the message according to its SIP routing. It works only while the sender’s application is connected. Otherwise, the message is not sent.
  • Twilio – sends messages through the Twilio SMS API.
  • PMT SMSC – sends messages through a Pattern Matched Technologies (PMT) SMSC connection.

Twilio credentials (shown when the SMS provider connection type is set to Twilio):

  • Twilio Account SID – specify your Twilio Account SID, a 34-character identifier that begins with “AC.”
  • Twilio Auth Token – specify your Twilio Auth Token, which is used together with the Account SID to authenticate API requests.

PMT SMSC credentials (shown when SMS provider connection type is set to PMT SMSC):

  • PMT API URL – specify the URL of the PMT API.
  • PMT API ID – specify your PMT API ID.
  • PMT User – specify your PMT API username.
  • PMT Password – specify your PMT API password.

Enable incoming call SMS notification – select this checkbox to send an SMS to the called number when a call arrives and the end user’s PortaPhone application is not connected. Use this option to reach customers whose devices are unable to receive push notifications. The SMS text is defined by the template below and can include a link.

Template for the SMS text – specify the text of the SMS notification. The template supports the placeholders {APP_NAME}, {FROM}, and {DEEP_LINK}.

App name – specify the name of your application as it should appear in the SMS text, for example, PortaPhone. Recipients will see this name as the application that sent the message. This name replaces {APP_NAME} in the template. Keep the name short, as SMS messages are limited to 160 characters.

Deep link – specify the base link that replaces {DEEP_LINK} in the SMS text. A deep link is a web link that opens the PortaPhone mobile application when the customer taps it. The domain in this link must match the deep link domain configured for your branded mobile application, and that domain must be set up to open the application. Otherwise, the link opens in a browser. Contact the PortaOne team to get the correct domain and to set it up.

From number – specify the phone number the SMS notification will be sent from, e.g., +18445001690.

PortaPhone Connection to SMS provider.

Domains and certificates

Link copied to clipboard

Core domain – the hostname PortaPhone’s mobile and web applications use to connect to their backend (see preparation step 1). It is also used by an internal diagnostics dashboard intended for PortaOne Support. This domain is not shown to end users.

Enable web dialer – select this checkbox to enable PortaPhone web. Clear this checkbox to run PortaPhone as a mobile-only deployment, without a browser-based application.

Dialer domain – specify the domain provided to your end users as the PortaPhone web application URL (see preparation step 1). Required when Enable web dialer is selected.

Enable logs proxy – select this checkbox to enable log collection through a logs proxy.

Logs proxy domain – specify the domain PortaPhone uses to receive logs. This domain needs its own DNS record and certificate, similar to the Core domain and Dialer domain.

Logs proxy host – specify the address of your own external log storage or analysis system. PortaPhone will forward the logs it receives to this address.

Generate certificates with Let’s Encrypt service – select the checkbox if you want PortaOne to generate a TLS certificate for you. Alternatively, upload your custom certificate and the private RSA key for your domain (see preparation step 2).

PortaPhone Domains and certificates.

Push services credentials

Link copied to clipboard

This section is optional. If you leave it unconfigured, PortaPhone will run without push notifications. Customers can still receive calls and messages, but only while the application is open and connected.

Use this section to configure the credentials PortaPhone requires to send mobile push notifications for incoming calls and messages to the PortaPhone mobile application. It contains two independent groups of fields: one for Apple Push Notification service (APNs), used by iOS, and one for Firebase Cloud Messaging (FCM), used by Android.

For both platforms, specify the application’s Bundle ID (for Android, the package name), the credentials that PortaPhone uses to authenticate with the push service notification, and the validity period, in seconds, for undelivered push notifications. Obtain these credentials from your own Apple Developer account and Firebase project. They must belong to the same Apple team and Firebase project as your branded PortaPhone application.

PortaPhone Push services credentials.

Disable functionalities

Link copied to clipboard

This section allows you to enable or disable individual PortaPhone features for all your customers. Each checkbox controls the availability of a specific feature, such as voicemail or call recording. Disabling a feature removes it from the application entirely.

This section applies only when the VoIP system connection type is set to PortaSwitch.

PortaPhone Disable functionalities.

Other settings

Link copied to clipboard

Core logger level – select the level of detail recorded in the PortaPhone application logs. The default value is Info. Other available values: Emergency, Alert, Critical, Error, Warning, Notice, Debug. A high log level can quickly use up disk space on a production installation, so discuss with the PortaOne team before enabling it.

Enable debug logs on Adapter – select this checkbox to record detailed technical information in the built-in adapter’s logs, useful for troubleshooting. This can quickly use up disk space on a production installation, so discuss with the PortaOne team before enabling it.

Tenant IDs to Adapter URLs – specify a mapping between tenant IDs and adapter API URLs, for deployments where one PortaPhone core instance serves multiple tenants, each connected to a different adapter. Separate each key from its value with an equal sign, and separate multiple pairs with a comma or semicolon, e.g., tenant1=https://tenant1.example.com;tenant2=https://tenant2.example.com.

Vue app update info interval – specify how often, in milliseconds, PortaPhone web refreshes the customer’s account information. Default: 60000 (1 minute).

Vue app update contacts interval – specify how often, in milliseconds, PortaPhone web refreshes the contact list. Default: 0.

Call history update interval – specify how often, in milliseconds, PortaPhone web refreshes call history. Default: 60000 (1 minute).

Post-call history refresh delay – specify how many milliseconds PortaPhone web waits after a call ends before refreshing call history. Default: 3000.

Voicemails update interval – specify how often, in milliseconds, PortaPhone web refreshes the voicemail list. Default: 1800000 ( 30 minutes).

Core API request timeout – specify how many milliseconds PortaPhone web waits for a response from PortaPhone Core before the request times out. Default: 30000 (30 seconds).

Widget auto-login allowed origins – specify which web pages may automatically sign in the embedded PortaPhone web widget. Enter the address of each page as the protocol and domain name, plus the port only if it is not the standard one, for example, https://portal.example.com or https://portal.example.com:8443. Separate multiple entries with commas. PortaPhone ignores auto-login requests from any other page, but customers can still sign in manually.

Widget embedding allowed origins – specify which websites can embed the PortaPhone web widget. Use exact addresses, without wildcards, e.g., https://portal.example.com. Separate multiple entries with a comma. Leave empty to allow embedding from any website. Websites already listed in Widget auto-login allowed origins do not need to be repeated here.

Call recording play button disable – select this checkbox to hide the playback button for call recordings in the PortaPhone web application.

Hide app name in drawer – select this checkbox to hide the application name shown next to the logo in the navigation menu of PortaPhone web. Useful when your logo image already includes your brand name.

Google Tag Manager ID – specify the Google Tag Manager container ID used for analytics in PortaPhone web.

Disabled audio codecs – specify the audio codecs that are turned off by default in PortaPhone web. Separate multiple entries with a comma. Available values: opus, g722, ilbc, pcmu, pcma. Customers can turn them back on in their settings, unless Lock codec configuration is selected.

Disabled video codecs – specify the video codecs that are turned off by default in PortaPhone web. Separate multiple entries with a comma. Available values: h264_baseline, h264_main, h264_high, h265, vp8, vp9, av1. Customers can turn them back on in their settings, unless Lock codec configuration is selected.

Lock codec configuration – select this checkbox to make the codecs disabled above permanent. PortaPhone web no longer offers these codecs in calls, and the codec section is removed from the customers’ settings entirely. When this checkbox is cleared, the disabled codecs are only turned off by default. Customers can turn them back on, or disable other codecs, in their settings.

Default interface language – select the language customers see until they choose a different one in the application settings, including on the login page. This setting applies to new customers only; customers who have already selected a language keep their choice. Default: English.

UI wording overrides – specify custom text to override specific option names in the PortaPhone web application. Each entry is a JSON object mapping a text key to its replacement text per language, for example: {“label.login”: {“en”: “Enter username”, “es”: “Introduce tu usuario”}}. Use apostrophes, not double quotes, inside the replacement text. If a key is incorrect, a value is missing, or the JSON is invalid, the override has no effect.

OTP ignore accounts – specify phone numbers or account IDs that are accepted with any OTP code, without verification. This option is intended for demo or testing purposes only and should not be used in a production deployment.

User data update interval – specify how often, in milliseconds, PortaPhone re-fetches and caches each signed-in account’s data from the connected system (PortaSwitch or externally hosted BSS adapter). This cache also lets active sessions keep working briefly if the system becomes temporarily unavailable. Default: 0 (disabled – data is fetched only when needed, with no proactive refresh).

Notification retention – specify how many days PortaPhone keeps in-app notifications before deleting them. In-app notifications are messages that appear in the notification list of the PortaPhone application, such as announcements, promotions, system messages, and new-login security alerts. PortaPhone deletes only notifications that the customer has already seen and that are older than this number of days. Default: 0 (disabled, notifications are kept indefinitely).

Notification senders whitelist – specify which PortaBilling account IDs are allowed to send an in-app notification to another customer through the PortaPhone API. This prevents a regular customer account from sending arbitrary notifications to other customers; only accounts you list here, such as a dedicated admin or system account, can send them. This option is relevant only when in-app notifications are enabled in Disable functionalities. Leave empty to block all notifications sent this way.

Minimum supported app version – specify the minimum PortaPhone mobile application version customers can use. Customers on an older version are prompted to update. Leave empty to disable this check.

Display env variables in LiveDashboard – select this checkbox to add the environment variables configured for the PortaPhone backend to the PortaPhone built-in operational dashboard. These variables include sensitive values such as database credentials, encryption keys, and provider credentials for push notifications and SMS. We recommend disabling this option in production.

Enables SDP filtering before sending offer – select this checkbox to remove speaking-indicator and network-quality-estimation data from the outgoing call setup data, reducing its size so it fits within the network’s packet size limit (MTU). If Preserve static codecs during SDP filtering is not enabled, this also removes older telephony codecs, such as G.711 and G.729, from the call setup data.

Events retention – specify how many days monitoring events (such as a customer’s SIP registration, a call start, and a call end) are kept. Default: 0 (no limit – events are kept indefinitely).

Stats retention – specify how many days monitoring statistics are kept. Default: 0 (no limit – statistics are kept indefinitely).

Calls retention – specify how many days call records are kept for monitoring. Default: 0 (no limit – records are kept indefinitely).

Enable on-demand session migration – select this checkbox before updating your PortaPhone deployment from version 0.12.9 to version 0.13.0 or later. This keeps customers registered and signed in during the update. Disable this checkbox once the update is complete.

Adapter request deadline (seconds) – specify how many seconds PortaPhone waits for a response from the PortaSwitch API before canceling the request. Default: 30.

PortaPhone Other settings.

3. Deployment

Link copied to clipboard

To deploy your PortaPhone application, click Save & Deploy. To save the configuration and deploy it later, click Save for later.

4. Make test calls

Link copied to clipboard

Once PortaPhone is deployed, open the PortaPhone web application link and make test audio and video calls using the pre-configured accounts.

On this page

Docs for
What's new
Admin manuals
Handbooks
UI help
Developers documentation
  • Loading…