Native Contacts

This guide will walk you through integrating native contact functionality into your WeWeb application using Despia's SDK. Your WeWeb mobile app will be able to read all contacts on the user's device and import them into your application.

Prerequisites

  1. WeWeb Project: Have an existing WeWeb project set up

  2. Despia Account: Create a free Despia account at despia.com

  3. Despia Project: Create and link a Despia project with your WeWeb staging or production domain

Overview

The integration allows your WeWeb application to:

  • Request permission to access device contacts

  • Read all contacts from the user's device

  • Import contact data (names and phone numbers) into your WeWeb application

  • Display contacts in a list or send them to your backend

1

Set Up Contact Permission Request

First, you need to request permission from users to access their contacts.

1.1 Add Permission Button

  1. In your WeWeb editor, add a button to your page

  2. Name it "Allow Contacts"

  3. This can be part of your onboarding flow or settings page

1.2 Create Permission Workflow

  1. Click on the button and add a new workflow

  2. Name the workflow: ask for contacts permission

  3. Add a "Custom JavaScript" action

  4. Name the action: Despia SDK Contact Permission

1.3 Add Permission Code

In the code editor, paste the following:

window.despia = "requestcontactpermission://"

This deep link triggers the native permission dialog on the user's device.

2

Create Contact Storage Variable

  1. Go to your WeWeb variables

  2. Create a new variable named Contacts

  3. Set the type to Array

  4. Initially, add a sample value for easier development:

    [
  {
    "name": "John Doe",
    "number": "+1234567890"
  }
]

  5. Once development is complete, clear this to an empty array []

3

Set Up Contact Reading Functionality

3.1 Add Fetch Contacts Button

  1. Add another button below the permission button

  2. Name it "Fetch Contacts"

3.2 Create Read Contacts Workflow

  1. Click on the button and add a new workflow

  2. Name the workflow: read contacts

  3. Set the trigger to "On click"

3.3 Add Contact Reading Code

  1. Add a "Custom JavaScript" action

  2. Name it: Despia SDK Read Contacts

  3. In the code editor, paste the following asynchronous handler:

window.despia = "readcontacts://"

const variable = "contacts";

return new Promise((resolve, reject) => {
    const startTime = Date.now();
    const timeout = 5000;

    function checkVariable() {
        if (window[variable] !== undefined) {
            resolve(window[variable]);
        } else if (Date.now() - startTime < timeout) {
            setTimeout(checkVariable, 100);
        } else {
            reject(`Timeout: ${variable} not available after ${timeout}ms`);
        }
    }

    checkVariable();
});

4

Format Contact Data

Despia returns contacts in a specific format that needs to be converted to a JSON array for WeWeb.

4.1 Add Formatting Function

  1. In your workflow, add another "Custom JavaScript" action after the read contacts action

  2. Name it: Format Despia Contact JSON

  3. Add the following formatting code:

const input = context.workflow['CONTEXT-ID-FROM-ABOVE-STEP'].result;

const result = Object.entries(input).map(([name, numbers]) => ({
    name,
    number: numbers[0]
}));

return result;

4.2 Update Contacts Variable

  1. Add a "Change variable value" action

  2. Name it: Update Contacts Variable

  3. Select the contacts variable

  4. Set it to "Replace all items with"

  5. Use the result from the formatting action

5

Display Contacts in a List

5.1 Add List Component

  1. Add a List component to your page

  2. The list should have text elements for name and phone number

5.2 Configure List Binding

  1. Select the list item

  2. Go to "Repeat" settings

  3. Bind the items to your contacts variable

  4. For the name text element, bind to item.name

  5. For the phone number element, bind to item.number

6

Testing Your Implementation

6.1 Publish to WeWeb

  1. Click "Publish" in WeWeb

  2. Choose "Publish to WeWeb subdomain" or your custom domain

  3. Add a comment for version tracking

6.2 Test on Device

  1. Open your Despia app on your mobile device

  2. Navigate to your WeWeb application

  3. Click "Allow Contacts" (first time only)

  4. Click "Fetch Contacts"

  5. Select contacts to share (iOS) or grant permission (Android)

  6. Your contacts should appear in the list

Advanced Features

Sending Contacts to Backend

Once contacts are in your WeWeb variable, you can:

  • Send them to Xano

  • Store in Supabase

  • Process with any backend service

Error Handling

Add error handling to your workflows:

try {
    // Your contact reading code
} catch (error) {
    console.error('Failed to read contacts:', error);
    // Show user-friendly error message
}

Permission Status Check

You can check if permission was granted by verifying if the contacts variable is populated after the request.

Best Practices

  1. Onboarding Integration: Include contact permission in your app's onboarding flow

  2. Clear Communication: Explain why you need contact access before requesting permission

  3. Privacy: Only request contacts when necessary and handle data securely

  4. Empty States: Design for cases where users deny permission or have no contacts

  5. Performance: For large contact lists, consider pagination or lazy loading

Troubleshooting

Contacts Not Loading

  • Ensure permission was granted

  • Check that the Despia handler is properly initialized

  • Verify your WeWeb domain is correctly linked in Despia

Format Issues

  • Make sure the formatting function is correctly parsing Despia's response

  • Check the browser console for any JavaScript errors

Permission Denied

  • You cannot re-request permission programmatically on iOS

  • Users must go to device settings to re-enable permission

Need Help?

For additional support or questions, please contact our support team at support@despia.com

Updated on
How it Works?