Manual

The same texts as under "Manual" in the app, here to look up and to link. As of version 1.6.0.

Overview

digoDial is a menu bar app that remote-controls an Asterisk phone system (computer telephony integration).

The app makes no calls itself and carries no audio: dialing, answering and hanging up always happen on the phone; digoDial only sends the commands to the PBX over the Asterisk Manager Interface (AMI).

The phone icon in the menu bar shows the connection state and opens the menu with the dial field, active calls and the call history.

Getting started

Set up the connection: Settings > Connection. Enter host and port of the PBX (default 5038), AMI user and password. Only enable "Use TLS" if the PBX offers AMI over TLS (otherwise the test fails with "bad protocol version"). "Test connection" checks the credentials right away; afterwards the password is stored only in the macOS keychain.
Default for phone links: The button "Set as default for tel: links" registers digoDial for tel: and callto: links from other programs.
Requirements on the PBX (one-time, see the README in the repository): an AMI user with the permissions read=call,system and write=call,originate,system, and a dial context that can reach internal and external destinations.

Dialing

All routes follow the same flow: digoDial tells the PBX (Originate) to ring your own phone first; once it picks up, the PBX dials the destination and connects both.

Dial field in the menu: Type a number and press Enter to dial.
Phone links: tel: and callto: links from any app, as well as digodial://call?number=...
Call history: Clicking an entry dials the number again (whether incoming, outgoing or missed).
Keyboard shortcut: By default, Shift+Option+Cmd+D dials the number currently selected in the frontmost app. You can change the combination under Settings > Dialing in the "Keyboard shortcut" field (click the field, press the new keys, confirm with "Save"). If it does not respond, it is probably already taken by macOS, another program or a tool such as BetterTouchTool or Raycast; choose a different one then. If no phone number is selected, the hint "No phone number selected" appears briefly. On the first press macOS asks for the Accessibility permission (the app simulates cmd+C to read the selection).
Context menu: Selected number > right-click > "Call with digoDial" (directly in the menu or under "Services", depending on the app; macOS picks up the service automatically after installation).
Display on the phone: While the call is being set up, the phone shows the CallerID name stored in the settings plus the destination number.
Number format: Region and dial format (E.164, 00-international, national) are in the "Dialing" tab. The app normalizes input automatically (e.g. 069... to +4969...). If a local area code is stored there, input without a leading 0 or + and with at least 6 digits automatically gets this area code prepended (e.g. 26546118 to 06926546118).

Name search: If you type a name instead of a number in the dial field (at least one letter), the section "Address book" appears below with matches from macOS Contacts and the LDAP directory, each with all stored numbers. Clicking a number dials it immediately and clears the field.

Auto-answer

With "Auto-answer" (Telephony tab), your own phone picks up by itself when dialing and the call to the destination starts immediately, like a classic CTI solution. Technically the app sends the SIP header "Call-Info: ...;answer-after=0".

The phone has to allow this: On Snom devices, set "Intercom Policy" (answer_after_policy) to "only in idle"; normal incoming calls then keep ringing as usual.

Which audio device the phone uses is decided by the phone alone (on Snom devices the setting call_info_audio_device); the app does not control the target device.

Incoming calls

Screen overlay: For an incoming call, a large window appears in the upper third of the screen with the resolved name, number and (optionally) the called extension together with your own dialed number. Buttons: "Answer" (answers the call on the phone, see Device control), "Decline" (hangs up), "Copy number", "Close". The overlay closes by itself as soon as the call is answered or ended.
macOS notifications: A notification with the same actions also appears; a missed call creates its own notification with "Call back".
Call window: While a call is connected, incoming or outgoing, a slim bar floats above all windows with name, number and call duration. Buttons: "Copy number", "Transfer" (opens a field for the extension, Enter transfers) and "Hang up". You can move the bar by its background and it reappears in the same place on the next call. It closes as soon as the call ends.
Switches: Overlay, extension display, call window and notifications can each be turned on and off in the "Signaling" tab.

Device control (Snom)

For the "Answer" button, digoDial controls the desk phone directly through its web interface (key press over HTTP). In the "Signaling" tab under "Device control (Snom)", enter the phone URL (e.g. http://192.0.2.45), the web user and the password (the password goes into the keychain). "Answer via" decides whether the call is answered on the headset or via speakerphone.

Without these details the Answer button is hidden in the overlay.

Name lookup

Incoming and outgoing numbers are resolved to names in this order: macOS Contacts (permission required), LDAP directory (server, base DN, bind details, filter template with {number}), HTTP directory (URL template with {number}, optional header, JSON path). Results are remembered for the configured cache duration. Numbers that cannot be resolved are shown unchanged.

Voicemail and Do Not Disturb

Voicemail: The "Voicemail" field must match the Asterisk mailbox exactly, usually in the form 1234@default. The counter in the menu follows the mailbox in both directions (a new message raises it, listening or deleting lowers it). For new messages, a red counter badge on the menu bar icon shows the same number (from 100 as "99+").
Listen button: As long as the mailbox is configured, a button with a play symbol appears to the right of the number in the voicemail row. One click dials the listen shortcut stored in the "Voicemail & DND" tab - your own phone picks up automatically (auto-answer) on its configured audio device and the PBX mailbox menu (VoiceMailMain) starts right away. Without a shortcut the button stays hidden.
The listen shortcut requires a matching dialplan entry on the PBX, e.g. exten => 55,1,VoiceMailMain(1234@default,s).
Do Not Disturb (DND): The switch in the menu sets or deletes an entry in the Asterisk database (family/value in the "Voicemail & DND" tab). For DND to take effect, the PBX dialplan has to check the entry before ringing - an example is in the README.

Settings overview

Connection: PBX, AMI user and password, TLS, default app for tel: links.
Telephony: own extension (DND key), monitored extensions (IMPORTANT: on PBXs whose channel names carry peer names, enter the peer name here, e.g. snom-phone-1 instead of 10), dial devices, originate context, CallerID display name, auto-answer.
Dialing: region, dial format, keyboard shortcut, launch at login.
Signaling: overlay, extension/number display, call window, macOS notifications, device control (Snom, web user) with "Answer via".
Name Lookup: contacts, LDAP, HTTP, cache duration.
Voicemail & DND: voicemail, DND family and value.
License: status of trial or full version, purchase and "Restore purchases".

Trial and full version

digoDial is free in the Mac App Store. Without a purchase, showing incoming calls with names, the macOS notifications, Do Not Disturb and voicemail remain usable.

Full version: Dialing by every route (dial field, name search, keyboard shortcut, context menu, phone links, call history), Transfer, the call history and the call window. It is unlocked permanently with a one-time in-app purchase.
Trial: "Try all features free for 5 days" unlocks everything for five days. The trial is tied to the Apple ID and can only be started once, even after a reinstall. Afterwards the app falls back to the free features without losing any settings.
Unlocking: in the "License" tab of the settings or via the row at the bottom of the menu. A locked feature shows a notice with a purchase button when used.
Restore purchases: On another Mac or after a reinstall, "Restore purchases" in the "License" tab brings back the full version.

Troubleshooting

"Connection failed: -9836: bad protocol version": TLS is enabled, but the PBX speaks plain-text AMI on this port. Turn off TLS.
No notifications: macOS sometimes silently refuses the request for ad-hoc builds. Allow digoDial manually in System Settings > Notifications; after rebuilding the app the permission may be needed again.
Voicemail counter stays 0: Check the voicemail field - it must match the PBX exactly (e.g. 1234@default; typos are the most common cause).
"Call with digoDial" is missing in the context menu: In System Settings > Keyboard > Keyboard Shortcuts > Services > Text, check that the service is ticked. It only applies to selected text; in some apps it sits in the "Services" submenu.
Outgoing calls do not appear: The monitored extension must match the PBX channel name (peer name, see the Telephony tab).
Phone web interface locked (device control): After several failed attempts the Snom blocks its web interface for a few minutes; wait briefly and check the credentials.

Licenses

digoDial uses the following open-source libraries, both under the MIT license.

GRDB.swift

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

PhoneNumberKit

The MIT License (MIT)

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

About

digoDial 1.6.0 (3) - native macOS app (SwiftUI). Call history and configuration stay local; passwords are stored only in the macOS keychain.