Skip to main content

URL Handler

BusyContacts supports URL handlers for showing a contact and creating a new contact.

Following is a sample contact vCard that will be used in the examples below.

BEGIN:VCARD  
VERSION:3.0  
PRODID:-//Apple Inc.//Mac OS X 10.8.2//EN  
N:;;;;  
FN:Apple  
ORG:Apple;  
EMAIL;type=INTERNET;type=pref:test@apple.com  
X-ABShowAs:COMPANY  
UID:f90221ac-84a8-4f40-a699-5930b59a24d1  
X-ABUID:B8FB81A6-659D-4E66-B1B7-97A95A144C83:ABPerson  
END:VCARD

Showing Contacts in BusyContacts​

You can show a contact in BusyContacts by opening the busycontacts://show/ URL. It takes 1 parameter, either the UID, X-ABUID, or an email address of the contact. The parameter must be URI encoded.

Here are some example URLs to show the sample contact:

busycontacts://show/test@apple.com

busycontacts://show/f90221ac-84a8-4f40-a699-5930b59a24d1

busycontacts://show/B8FB81A6-659D-4E66-B1B7-97A95A144C83:ABPerson

To open the contact in a separate floating window, use busycontacts://open/ instead.

Opening Contacts in BusyContacts from Alfred​

If you're using Alfred, it can be configured to open contacts in BusyContacts instead of macOS Contacts. Note: Alfred 2.7.2 and BusyContacts 1.0.3 or later are required.

Open Alfred > Preferences > Features > Contacts > Advanced. Check the URL Handler checkbox and enter busycontacts://show/{uid}.

![Alfred](https://www.busymac.com/images/bct-alfred.png)

Now when you search for a contact in Alfred and open it, it will be opened in BusyContacts.

Contact the developers of Alfred if you need help configuring Alfred to open contacts in BusyContacts.

Opening Contacts in BusyContacts from LaunchBar​

If you're using LaunchBar, it can be configured to open contacts in BusyContacts instead of macOS Contacts. Note: LaunchBar 6.2.1 and BusyContacts 1.0.3 or later are required.

Currently, LaunchBar does not expose a UI for setting BusyContacts as the default app to open contacts from LaunchBar, but it can be configured using Terminal.

  1. Quit LaunchBar.
  2. Launch Terminal (in /Applications/Utilities).
  3. Paste the following text and press return:
    defaults write at.obdev.LaunchBar ShowInAddressBookURLPrefix busycontacts://show/
  4. Quit Terminal.
  5. Launch LaunchBar.

Now when you search for a contact in LaunchBar and open it, it will be opened in BusyContacts.

If you wish to reset this setting and use macOS Contacts as the default app to open contacts from LaunchBar, repeat the steps above and replace the pasted text in step 3 with this:

defaults delete at.obdev.LaunchBar ShowInAddressBookURLPrefix

Contact the developers of LaunchBar if you need help configuring LaunchBar to open contacts in BusyContacts.

Opening Contacts in BusyContacts from other apps​

In addition to launchers like Alfred and LaunchBar, it may be possible to configure other third-party apps to open contacts in BusyContacts using the following information.

Third-party apps open contacts in macOS Contacts using the addressbook://X-ABUID URL scheme. To open the contacts in BusyContacts instead, the third-party app needs to be configured to pass the X-ABUID to busycontacts://show/X-ABUID instead.

For example, the following URL will open a contact in macOS Contacts:

addressbook://B8FB81A6-659D-4E66-B1B7-97A95A144C83:ABPerson

If you change the addressbook:// prefix to busycontacts://show/, the contact is opened in BusyContacts:

busycontacts://show/B8FB81A6-659D-4E66-B1B7-97A95A144C83:ABPerson

Contact your third-party app developer for help opening contacts in BusyContacts.

Creating new contacts in BusyContacts​

You can create a new contact in BusyContacts by opening the busycontacts://new/ URL. It takes 1 parameter, a natural language string that represents the new contact. You can optionally include a hint for the name of the address book to put the new contact into via a " /Hint" suffix. The parameter string must be encoded.

Here are some example URLs to create a new contact

busycontacts://new/Bob%20Jones%20555-1212

busycontacts://new/Bob%20Jones%20123%20Main%20Street,%20Anytown%20USA%20/iCloud

XCode sample code​

If you are an app developer, following is sample code in Objective-C.

Here is sample code to programmatically show a contact:

- (void)busycontactsShowContact:(NSString *)uidOrEmail {
  NSString *url = [NSString stringWithFormat:@"busycontacts://show/%@", [uidOrEmail stringByURIEncoding]];
  [[NSWorkspace sharedWorkspace] openURL:[NSURL URLWithString:url]];
}

Below is a category on NSString for URI encoding a string:

@interface NSString (URIEncoding)

- (NSString *)stringByURIEncoding;

@end

@implementation NSString (URIEncoding)

- (NSString *)stringByURIEncoding {
  // same as -stringByAddingPercentEscapesUsingEncoding but escapes '/' and '?'
  const CFStringRef leaveUnescaped = NULL;
  const CFStringRef forceEscaped = CFSTR("!*'();:@&=+$,/?%#[]");
  CFStringRef escapedStr = CFURLCreateStringByAddingPercentEscapes(kCFAllocatorDefault,
    (CFStringRef) self, leaveUnescaped, forceEscaped, kCFStringEncodingUTF8);
  return [NSMakeCollectable(escapedStr) autorelease];
}

@end
Last updated on