afv-library/skills/mobile-platform-native-capabilities-integrate/references/contacts.md

Contacts Service Grounding Context

The following content provides grounding information for generating a Salesforce LWC that leverages contacts facilities on mobile devices. Specifically, this context will cover the API types and methods available to leverage the contacts API of the mobile device, within the LWC.

Contacts Service API

/*
 * Copyright (c) 2024, Salesforce, Inc.
 * All rights reserved.
 * For full license text, see the LICENSE.txt file
 */

import { BaseCapability } from '../BaseCapability.js';

/**
 * Use this factory function to get an instance of {@linkcode ContactsService}.
 * @returns An instance of {@linkcode ContactsService}.
 */
export function getContactsService(): ContactsService;

/**
 * Access contacts from a Lightning web component.
 * @see {@link https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-contactsservice.html|ContactsService API}
 */
export interface ContactsService extends BaseCapability {
  /**
   * 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.
   * @param options A {@linkcode ContactsServiceOptions} object to configure the {@linkcode ContactsService} request.
   * @returns A Promise object that resolves as an array of {@linkcode Contacts} objects. If an error is encountered, the array is empty.
   */
  getContacts(options?: ContactsServiceOptions): Promise<Contact[]>;

  /**
   * Save a contact record into the mobile device address book.
   * @param contact A {@linkcode Contacts} object.
   * @param options A {@linkcode ContactsServiceOptions} object to configure the {@linkcode ContactsService} request. Currently
   *                used to override the device's permission UX sequence text.
   * @returns A resolved promise returns a {@linkcode Contacts} object.
   */
  putContact(contact: Contact, options?: ContactsServiceOptions): Promise<Contact>;
}

/**
 * An object representing a contact.
 */
export interface Contact {
  /**
   * A stringified number unique to each contact. Generated by the native device at the time of contact creation.
   */
  id: string;

  /**
   * An object representing a contact's name.
   */
  name: ContactName;

  /**
   * An array of objects containing phone numbers for the contact.
   */
  phoneNumbers: ContactLabeledValue[];

  /**
   * An array of objects containing email addresses for the contact.
   */
  emails: ContactLabeledValue[];

  /**
   * An array of objects representing contact's addresses.
   */
  addresses: ContactAddress[];

  /**
   * An array of objects containing instant messaging (IM) usernames for the contact.
   */
  ims: ContactLabeledValue[];

  /**
   * An object representing a contact's organization.
   */
  organizations: ContactOrganization[];

  /**
   * A text field for any extra information about the contact.
   */
  note: string;

  /**
   * An array of objects containing URLs for the contact.
   */
  urls: ContactLabeledValue[];
}

/**
 * An object representing a contact’s address.
 */
export interface ContactAddress {
  /**
   * A string representing the type of address for a contact’s address.
   */
  type: string;

  /**
   * A string representing the street address for a contact’s address.
   */
  streetAddress: string;

  /**
   * A string representing the locality (also known as the “city”) for a contact’s address.
   */
  locality: string;

  /**
   * A string representing the region (also known as the “state” or “province”) for a contact’s address.
   */
  region: string;

  /**
   * A string representing the postal code for a contact’s address.
   */
  postalCode: string;

  /**
   * A string representing the country for a contact’s address.
   */
  country: string;
}

/**
 * An object representing a contact’s organization.
 */
export interface ContactOrganization {
  /**
   * A string representing the name of a contact’s organization.
   */
  name: string;

  /**
   * A string representing the department of a contact’s organization.
   */
  department: string;

  /**
   * A string representing the title the contact holds in the organization.
   */
  title: string;
}

/**
 * An object representing a contact’s name.
 */
export interface ContactName {
  /**
   * A string representing the contact’s family name (also known as “surname” or “last name”).
   */
  familyName: string;

  /**
   * A string representing the contact’s given name (also known as “first name”).
   */
  givenName: string;

  /**
   * A string representing the contact’s middle name.
   */
  middleName: string;

  /**
   * A string representing the contact’s name prefix.
   */
  namePrefix: string;

  /**
   * A string representing the contact’s name suffix.
   */
  nameSuffix: string;
}

/**
 * An object containing a label and a value for a miscellaneous piece of contact information.
 */
export interface ContactLabeledValue {
  /**
   * The display name that categorizes the data in value. In the following examples, home, homepage, and work are label properties.
   */
  label: string;

  /**
   * The value of the data specified in label.
   */
  value: string;
}

/**
 * An object representing an error that occurred when accessing {@linkcode ContactsService} features.
 */
export interface ContactsServiceFailure {
  /**
   * A value representing the reason for a contacts error.
   */
  code: ContactsServiceFailureCode;

  /**
   * A string value describing the reason for the failure. This value is suitable for use in user interface messages. The message is provided in English, and isn’t localized.
   */
  message: string;
}

/**
 * An object representing configuration details for a {@linkcode ContactsService} session.
 */
export interface ContactsServiceOptions {
  /**
   * Optional parameter, used by Android only. This only appears after an initial denial by the user. To use the default permission message, pass in an empty object.
   * The default permission message is “To import Contacts, permission is needed to access Contacts. Tap Allow in the following permissions dialog.”
   */
  permissionRationaleText?: string;
}

/**
 * Possible failure codes.
 */
export type ContactsServiceFailureCode =
  | 'USER_DISMISSED' // The user clicked the cancel button.
  | 'USER_DENIED_PERMISSION' // Permission was denied to access contacts (older versions of Android only).
  | 'USER_DISABLED_PERMISSION' // Android Only - Permission was denied.  User will need to go to app setting to turn on.
  | 'USER_RESTRICTED_PERMISSION' // The application is restricted (perhaps by parental controls) from accessing Contacts (iOS only).
  | 'SERVICE_NOT_ENABLED' // The service is not enabled and therefore cannot be used.
  | 'SAVE_OPERATION_FAILED' // The service couldn't save the contact record into the address book.
  | 'UNKNOWN_REASON'; // Generic error that is not captured by any of the above categories