Scripting
Getting Started
Documentation
Changelog
Getting Started
Documentation
Changelog

Contact

The Contact module in the Scripting app allows you to access and manage contacts on the device. You can create, query, update, and delete contacts, as well as manage contact groups and containers.

Overview of Data Structures

Type Description
ContactInfo Represents detailed information of a single contact.
ContactContainer Represents a contact storage container, such as local, Exchange, or CardDAV.
ContactGroup Represents a contact group for categorizing contacts.
ContactLabeledValue A labeled value, such as phone number or email address.
ContactPostalAddress Represents a postal address.
ContactSocialProfile Represents social profile information.
ContactInstantMessageAddress Represents instant messaging account information.

Creating a Contact

1try {
2  const contact = await Contact.createContact({
3    givenName: 'John',
4    familyName: 'Doe',
5    phoneNumbers: [{ label: 'mobile', value: '+1234567890' }],
6    emailAddresses: [{ label: 'work', value: 'john.doe@example.com' }]
7  })
8  console.log('Contact created:', contact)
9} catch (error) {
10  console.error('Failed to create contact:', error)
11}
  • Either givenName or familyName is required.
  • You may specify an optional containerIdentifier. If not provided, the contact is added to the default container.
  • Always handle potential errors due to permission issues or invalid input.

Updating a Contact

1try {
2  const updated = await Contact.updateContact({
3    identifier: contact.identifier,
4    phoneNumbers: [{ label: 'home', value: '+9876543210' }]
5  })
6  console.log('Contact updated:', updated)
7} catch (error) {
8  console.error('Failed to update contact:', error)
9}
  • identifier is required.
  • Only the provided fields will be updated; others remain unchanged.

Fetching Contacts

Fetch a Contact by Identifier

1try {
2  const contact = await Contact.fetchContact(contactId, { fetchImageData: true })
3  console.log('Contact fetched:', contact)
4} catch (error) {
5  console.error('Failed to fetch contact:', error)
6}

Fetch All Contacts

1try {
2  const contacts = await Contact.fetchAllContacts({ fetchImageData: false })
3  console.log('All contacts:', contacts)
4} catch (error) {
5  console.error('Failed to fetch contacts:', error)
6}

Fetch Contacts in a Container or Group

1try {
2  const contacts = await Contact.fetchContactsInContainer(containerId)
3  console.log('Contacts in container:', contacts)
4} catch (error) {
5  console.error('Failed to fetch contacts in container:', error)
6}
7
8try {
9  const groupContacts = await Contact.fetchContactsInGroup(groupId)
10  console.log('Contacts in group:', groupContacts)
11} catch (error) {
12  console.error('Failed to fetch contacts in group:', error)
13}
  • Set fetchImageData to true only if you need the contact's image data.

Deleting a Contact

1try {
2  await Contact.deleteContact(contactId)
3  console.log('Contact deleted')
4} catch (error) {
5  console.error('Failed to delete contact:', error)
6}

Contact Container Management

Fetch All Containers

1try {
2  const containers = await Contact.fetchContainers()
3  console.log('Contact containers:', containers)
4} catch (error) {
5  console.error('Failed to fetch containers:', error)
6}

Get the Default Container Identifier

1try {
2  const defaultContainerId = await Contact.defaultContainerIdentifier
3  console.log('Default container ID:', defaultContainerId)
4} catch (error) {
5  console.error('Failed to fetch default container:', error)
6}

Container types:

  • unassigned
  • local
  • exchange
  • cardDAV

Contact Group Management

Create a Contact Group

1try {
2  const group = await Contact.createGroup('Friends', defaultContainerId)
3  console.log('Group created:', group)
4} catch (error) {
5  console.error('Failed to create group:', error)
6}

Fetch Groups

1try {
2  const groups = await Contact.fetchGroups()
3  console.log('Groups:', groups)
4} catch (error) {
5  console.error('Failed to fetch groups:', error)
6}

Delete a Group

1try {
2  await Contact.deleteGroup(groupId)
3  console.log('Group deleted')
4} catch (error) {
5  console.error('Failed to delete group:', error)
6}

Managing Contact and Group Relationship

Add Contact to a Group

1try {
2  await Contact.addContactToGroup(contactId, groupId)
3  console.log('Contact added to group')
4} catch (error) {
5  console.error('Failed to add contact to group:', error)
6}

Remove Contact from a Group

1try {
2  await Contact.removeContactFromGroup(contactId, groupId)
3  console.log('Contact removed from group')
4} catch (error) {
5  console.error('Failed to remove contact from group:', error)
6}

Example ContactInfo Structure

1{
2  "identifier": "XXXX-XXXX",
3  "givenName": "John",
4  "familyName": "Doe",
5  "phoneNumbers": [{ "label": "mobile", "value": "+1234567890" }],
6  "emailAddresses": [{ "label": "work", "value": "john@example.com" }],
7  "postalAddresses": [{
8    "label": "home",
9    "street": "123 Apple St.",
10    "city": "Cupertino",
11    "state": "CA",
12    "postalCode": "95014",
13    "country": "USA",
14    "isoCountryCode": "US"
15  }]
16}

Important Notes

  • All API operations can fail due to reasons such as lack of permission or invalid parameters. Always use try-catch.
  • User permission is required to access contacts.
  • imageData should only be fetched if necessary to reduce memory usage.
  • Ensure the identifier is valid when performing update or delete operations.

Complete Example: Create and Fetch a Contact

1try {
2  const contact = await Contact.createContact({
3    givenName: 'Alice',
4    familyName: 'Smith',
5    phoneNumbers: [{ label: 'mobile', value: '+19876543210' }]
6  })
7  console.log('Contact created:', contact)
8
9  const fetched = await Contact.fetchContact(contact.identifier)
10  console.log('Fetched contact:', fetched.givenName)
11} catch (error) {
12  console.error('Operation failed:', error)
13}
Outline