elizaos--eliza/plugins/plugin-native-contacts/README.md

@elizaos/capacitor-contacts

Capacitor plugin providing an Android ContactsContract bridge for elizaOS agents. Enables reading, creating, and importing contacts on Android from TypeScript/JavaScript code. On web and Node.js the plugin provides an explicit fallback that returns empty contact lists and rejects writes.

What it does

• List contacts — query the device address book with optional text search and result limit.
• Create a contact — insert a new contact with a display name, phone numbers, and email addresses.
• Import vCard — parse RFC 6350 vCard text and bulk-insert the contacts.

Platform support

Platform	listContacts	createContact	importVCard
Android	Full	Full	Full
Web/Node	Returns []	Throws	Throws

Requirements

• @capacitor/core ^8.3.1 in the host app.
• Android runtime permissions must be granted by the host app:
  • READ_CONTACTS — required for listContacts.
  • WRITE_CONTACTS — required for createContact and importVCard.

The permissions are declared in the plugin's AndroidManifest.xml and are merged automatically by the Android build system.

Installation

bun add @elizaos/capacitor-contacts

Then sync Capacitor:

npx cap sync android

Usage

import { Contacts } from "@elizaos/capacitor-contacts";

// List contacts (optionally filtered)
const { contacts } = await Contacts.listContacts({ query: "Alice", limit: 50 });

// Create a contact
const { id } = await Contacts.createContact({
  displayName: "Alice Example",
  phoneNumber: "+15555550100",
  emailAddress: "alice@example.com",
});

// Import from vCard text
const { imported } = await Contacts.importVCard({ vcardText: myVCardString });

API

listContacts(options?)

Option	Type	Default	Description
query	string	—	Case-insensitive search across name, phone, and email.
limit	number	100	Max contacts to return. Must be 1–500.

Returns { contacts: ContactSummary[] }.

createContact(options)

Option	Type	Required	Description
displayName	string	Yes	Contact display name.
phoneNumber	string	No	Single phone number (convenience alias).
phoneNumbers	string[]	No	Multiple phone numbers.
emailAddress	string	No	Single email address (convenience alias).
emailAddresses	string[]	No	Multiple email addresses.

Returns { id: string } (the new contact's ContactsContract ID).

importVCard(options)

Option	Type	Required	Description
vcardText	string	Yes	Raw vCard text (vCard 2.1 / 3.0 / 4.0).

Parses FN, N, TEL, and EMAIL fields. Photo data is not imported. Returns { imported: ImportedContactSummary[] }.

ContactSummary

interface ContactSummary {
  id: string;
  lookupKey: string;
  displayName: string;
  phoneNumbers: string[];
  emailAddresses: string[];
  photoUri?: string;
  starred: boolean;
}

Building

bun run --cwd plugins/plugin-native-contacts build

Runs TypeScript compilation and Rollup to produce dist/esm/ (ESM) and dist/plugin.cjs.js (CJS).