getContacts(options)

Allows the user to pick one or more contacts from the device’s Contacts app. If needed, presents a permissions pop-up to the user to request access to contacts first, and then presents the user with the contacts selector.

  • A Promise object that resolves as an array of Contact objects. If an error is encountered, the array is empty.

  • A rejected promise returns a ContactsServiceFailure object containing details about the error.

This function presents a contacts selection list, and then returns a list of the contacts that were selected.

When this function is called, a list view displaying device contacts is displayed on the mobile device. The user can select any number of contacts, and then tap the check mark icon to continue.

  • getContacts() is a synchronous function. That is, JavaScript execution pauses while the selection list is on screen. The user must finish selecting contacts and tap the continue button, or cancel the operation, for the promise to resolve. Your component’s execution resumes when the promise resolves.
  • When contacts are selected, the result is returned via a fulfilled promise. Handle successful results in a then clause.
  • If an error occurs, the error is returned via a rejected promise. Handle errors in a catch clause.
  • If the user cancels contact selection, the promise is rejected with a ContactsServiceFailure.codevalue of USER_DISMISSED.
  • The contacts selection list is a device-native window, and can’t be customized.
  • While you can’t customize the contacts selection window itself, you can present a custom interface before contacts selection. After contacts selection, you can present another custom interface to offer additional options or features for processing the selected contacts.

See Also