Use the ContactsService API

Add ContactsService to a Lightning Web Component

In your component’s JavaScript file, import ContactsService using the standard JavaScript import statement. Specifically, import the getContactsService() factory function from the lightning/mobileCapabilities module, like so:

1import { getContactsService } from 'lightning/mobileCapabilities';

After it’s imported into your component, use the factory function to get an instance of ContactsService. With your ContactsService instance, use the utility functions and constants to verify availability. Then use contacts-related functions to select contacts from the device.

Test ContactsService Availability

ContactsService depends on physical device hardware and platform features. A component that uses ContactsService renders without errors on a desktop computer or in a mobile browser, but contacts-related functions fail. To avoid these errors, check if ContactsService functionality is available before you use it.

1handleGetContactsClick(event) {
2    const myContactsService = getContactsService();
3    if(myContactsService.isAvailable()) {
4        // Perform contacts-related operations
5    }
6    else {
7        // ContactsService not available, or consuming app hasn’t implemented it 
8        // Not running on hardware with contacts, address book, etc.
9        // Handle with message, error, beep, and so on
10    }
11}

Select Contacts from Device

It’s straightforward to create a custom contacts processing feature using ContactsService.

1. Open the contacts selection list view using getContacts().
2. Your user selects contacts from the list.
3. Process the results (the contacts data for the selected contacts).

For example:

1// Select on-device contacts, and then process them
2myContactsService.getContacts(options)
3.then((results) => {
4    // Do something with the contacts data
5    this.contacts = results;
6    console.log(results);
7})
8.catch((error) => {
9    // Handle cancellation, or selection errors here
10    this.contacts = [];
11    console.error('Error code: ' + error.code); + 
12    console.error('Error message: ' + error.message);
13});

See getContacts(options) for more details about how to handle contacts data, handle errors, and so on.

Save a Contact to Device

To save a contact to the device's address book, construct a valid Contact object and pass it to the putContact() method.

1. Create a Contact object in your JavaScript code with the desired details (name, phone, email, etc.). This data often comes from a Salesforce record.
2. Call putContact(), passing the Contact object.
3. Process the result, which is a Contact object of the successfully saved record, or handle the error.

For example:

1// First, create a contact object from your source data
2    const contactToSave = {
3        name: {
4            familyName: 'Doe',
5            givenName: 'John'
6        },
7        phoneNumbers: [{
8            label: 'Work',
9            value: '415-555-1212'
10        }],
11        emails: [{
12            label: 'Work',
13            value: 'john.doe@example.com'
14        }]
15};
16// Now, save the contact to the device
17myContactsService.putContact(contactToSave)
18.then((result) => {
19    // The contact was successfully saved.
20    console.log('Contact saved:', result);
21})
22.catch((error) => {
23// Handle errors here, such as the user denying permission or a failure to save.
24    console.error('Error code: ' + error.code);
25    console.error('Error message: ' + error.message);
26});

See the ContactsService API reference for full details about the Contact object structure.