📒Contacts

Let users access and create entries in the device's native contacts, directly from your app.

What is Contacts?

The Contacts feature gives your app access to the device's native contact list, letting users retrieve their existing contacts or create new ones without leaving the app. This is useful for features like inviting friends, syncing a personal address book, or letting users save a new contact your app provides.

Accessing contacts requires the user to grant permission the first time the feature is used, on both iOS and Android.

Prerequisites

This feature requires any paid plan. See all plans

Natively Dashboard Setup

1. Open your Natively app dashboard and navigate to Features > Contacts.

2. Toggle the feature to Enabled.

3. Enter the Permission Description.

4. Click Save.

5. Rebuild your app(s).

The Permission Description is the text shown to users when the OS asks them to grant contacts access. Explain clearly why your app needs this permission — for example: "We use your contacts to help you invite friends to the app".

You must rebuild your app for these changes to take effect.

Implementation

Choose your integration method below: Bubble.io Plugin (No-Code), JavaScript SDK (Code), or AI Agents (for AI-powered editors like Lovable, Base44, and Replit).

Initialization

Bubble.io Plugin

Check Plugin

Before starting, verify if the Natively plugin is already installed in your Bubble project.

1. Open your Bubble editor and navigate to the Plugins tab in the left sidebar.

2. Check Installed Plugins: Look through your list of installed plugins for "Natively iOS & Android app builder".

   • If it IS installed: Check the version number. If an update is available (e.g., you see a button saying "Update"), click it to ensure you have the latest features and bug fixes.

• If it is NOT installed: Click the + Add plugins button, search for "Natively", and click Install.

JavaScript SDK

Check SDK

Before writing any logic, ensure the Natively SDK is correctly installed and up-to-date in your codebase.

1. Open your project's main HTML file (or header settings) and look for the Natively script tag inside the <head> section.

2. Install/Update: If missing or outdated, add the following code. You can specify the SDK version in the URL (e.g., @2.26.0).

<head>
  <script async onload="nativelyOnLoad()" src="https://cdn.jsdelivr.net/npm/natively@2.26.0/natively-frontend.min.js"></script>
</head>

To ensure you are using the most up-to-date version, check the Natively GitHub releases page for the latest version number.

AI Agents

Initialize the SDK

AI-powered editors like Lovable, Base44, and Replit use the JavaScript SDK to implement Natively features. Before implementing any feature, the Natively SDK must be initialized in your project.

Copy the line below and paste it into your AI agent to check and set up the Natively SDK in your project.

Check if the following Natively SDK script is present in the <head> of index.html. If missing or outdated, add it: <script async onload="nativelyOnLoad()" src="https://cdn.jsdelivr.net/npm/natively@2.26.0/natively-frontend.min.js"></script><script>function nativelyOnLoad() { window.natively.setDebug(true); console.log("✅ Natively SDK loaded successfully."); }</script> For reference: https://docs.buildnatively.com/guides/integration/how-to-get-started https://github.com/buildnatively/js-sdk/releases

Setup Logic

Bubble.io Plugin

[Element] Natively - Contacts

Set the element's data type field to ContactObject (Natively - ...).

Events:

• Get All Contacts Success - fires when contacts are successfully retrieved.

• Get All Contacts Failed - fires if retrieving contacts fails.

• Create Contact Success - fires when a new contact is successfully created.

• Create Contact Failed - fires if creating a contact fails.

States:

• Get Contacts Result — list of ContactObject, each with:

  • FirstName;

  • LastName;

  • Phones — comma-separated if the contact has multiple phone numbers (e.g. "0543523,124334234");

  • Emails — comma-separated if the contact has multiple emails (e.g. "[e-mail],[e-mail]");

  • ID — unique contact identifier on the device.

• Create Contact ID Result — the ID of the newly created contact, after Create Contact.

• Create/Get Contacts Status — result status after calling Create Contact or Get All Contacts.

Actions:

• Get All Contacts — returns a list of ContactObject .

• Create Contact — returns the new contact's ID:

  • First name;

  • Last name;

  • Phone;

  • Email;

JavaScript SDK

// ============================================================================
// NATIVELY CONTACTS - DOCUMENTATION & EXAMPLES
// ============================================================================

const contacts = new NativelyContacts();

// ============================================================================
// ALL AVAILABLE METHODS
// ============================================================================
// contacts.getAllContacts(callback)
//   - Retrieves all contacts stored on the device.
//
// contacts.createContact(firstName, lastName, email, phone, callback)
//   - Creates a new contact on the device.
//   - firstName: string
//   - lastName: string
//   - email: string
//   - phone: string

// ============================================================================
// CALLBACK RESPONSE FIELDS - getAllContacts
// ============================================================================
// resp.status: string — "SUCCESS" or "FAILED"
// resp.contacts: array — list of contact objects, each with:
//   id: string, firstName: string, lastName: string,
//   phones: array of strings, emails: array of strings

// ============================================================================
// CALLBACK RESPONSE FIELDS - createContact
// ============================================================================
// resp.status: string — "SUCCESS" or "FAILED"
// resp.id: string — the new contact's ID

// --- Contacts. Get All Contacts Example. Start ---

const get_all_contacts_callback = function (resp) {
  console.log(resp.status); // "SUCCESS" or "FAILED"

  resp.contacts.forEach(contact => {
    console.log(contact.id);         // unique contact identifier on the device
    console.log(contact.firstName);
    console.log(contact.lastName);
    console.log(contact.phones);     // array of phone numbers
    console.log(contact.emails);     // array of email addresses
  });
};

contacts.getAllContacts(get_all_contacts_callback);

// --- Contacts. Get All Contacts Example. End ---


// --- Contacts. Create Contact Example. Start ---

const firstName = "Jane";
const lastName = "Doe";
const email = "[e-mail]";
const phone = "[phone]";

const create_contact_callback = function (resp) {
  console.log(resp.status); // "SUCCESS" or "FAILED"
  console.log(resp.id);     // the new contact's ID
};

contacts.createContact(firstName, lastName, email, phone, create_contact_callback);

// --- Contacts. Create Contact Example. End ---

AI Agents

AI-powered editors like Lovable, Base44, and Replit use the JavaScript SDK to implement Natively features.

Copy the line below and paste it into your AI agent.

[Your feature description] using the Natively Contacts SDK: const contacts = new NativelyContacts(); contacts.getAllContacts(callback) retrieves all contacts stored on the device, returning resp.status ("SUCCESS" or "FAILED") and resp.contacts (array of contact objects, each with id, firstName, lastName, phones (array), emails (array)). contacts.createContact(firstName, lastName, email, phone, callback) creates a new contact, returning resp.status ("SUCCESS" or "FAILED") and resp.id (the new contact's ID). For reference: https://docs.buildnatively.com/guides/integration/contacts

Replace the placeholder at the beginning with a description of what you want to build - for example: "Let the user create a new contact from a form with name, email, and phone fields".

How to use

Check resp.status before using the result

Both getAllContacts and createContact return a status field - always confirm it's "SUCCESS" before iterating over resp.contacts or using resp.id.

Handle multiple phone numbers and emails

A contact may have more than one entry in phones or emails - don't assume a single value; iterate over the array or pick the one relevant to your use case (e.g., the first entry).

Use this to power an invite-a-friend flow

A common use case is letting users pick from their existing contacts to invite friends to your app - retrieve contacts with getAllContacts, then let the user select recipients from the results.

Troubleshooting

Contacts permission denied

If the user previously denied contacts access, the feature can't prompt again automatically. Direct them to Open App Settings to manually re-enable the permission.

getAllContacts returns an empty list

This is expected if the user's device genuinely has no contacts.

Not working in a web browser

This is a native feature and will not work in a standard web browser. Test on a real device using a Natively build or the Preview app.