Contacts

Permission settings are required

fetchContactsBefore using it, you need to set contact permissions. Please first check the permission setup guide.

---

Fetch Contacts

SDK function: fetchContacts

fetchContactsis a function that fetches the user's contact list page by page.

Signature

function fetchContacts(options: {
  size: number;
  offset: number;
  query?: {
    contains?: string;
  };
}): Promise<ContactResult>;

Parameters

• options · Required

  This is the options object specified when fetching contacts.

  • options.size · Required

    The number of contacts to fetch at once. For example, if you pass 10, it fetches up to 10 contacts.
  • options.offset · Required

    This is the starting point for the contacts to fetch. When calling it for the first time, 00 nextOffset you should pass. After that, use the

    • options.query · Required

      This is an additional filtering option.

      • options.query.contains · Required

        Use this when you want to fetch only contacts whose names contain a specific string. If you do not pass this value, all contacts are fetched.

Properties

• openPermissionDialog

  Displays a dialog to request contact read permission again. The user can choose one of "Allow", "Allow Once", or "Don't Allow". If "Allow" or "Allow Once" is selected, allowedit returns deniedis returned.
• getPermission

  Returns the current status of contact read permission. allowedis the state where the user has granted contact read permission. deniedis the state where the user has denied contact read permission. notDeterminedis the state where a contact read permission request has never been made. If contact permission is denied in the Toss app settings, osPermissionDeniedis returned.

Return value

• Promise<ContactResult>

Returns an object containing the contact list and pagination information.

• result: the fetched contact list.
• nextOffset: the offset value to use for the next call. If there are no more contacts to fetch, null.
• done: indicates whether all contacts have been fetched. If all have been fetched, true.

Contact Permission Error

Error type: FetchContactsPermissionError

This is an error that occurs when contact permission is denied. When an error occurs, error instanceof FetchContactsPermissionErroryou can check it with.

Signature

class FetchContactsPermissionError extends PermissionError {
  constructor();
}

Example

Fetch a contact list containing a specific string

This is an example of fetching a contact list. Press the "Check Permission" button to check the current contact read permission. If the user denies permission or the system restricts permission, FetchContactsPermissionErrorit returns. You can press the "Request Permission" button to request contact read permission.

js

import { fetchContacts, FetchContactsPermissionError } from '@apps-in-toss/web-framework';

async function handleFetchContacts() {
  try {
    const response = await fetchContacts({
      size: 10,
      offset: 0,
      query: { contains: 'Kim' },
    });

    return response;
  } catch (error) {
    if (error instanceof FetchContactsPermissionError) {
      console.log('No contact read permission');
    }
    console.error('Failed to fetch contacts:', error);
  }
}

async function handleGetPermissionForFetchContacts() {
  const permission = await fetchContacts.getPermission();
  return permission;
}

async function handleOpenPermissionDialogForFetchContacts() {
  const permission = await fetchContacts.openPermissionDialog();
  return permission;
}

React

import { ContactEntity, fetchContacts, FetchContactsPermissionError } from '@apps-in-toss/web-framework';
import { useState } from 'react';

function ContactsList() {
  const [contacts, setContacts] = useState<{
    result: ContactEntity[];
    nextOffset: number | null;
    done: boolean;
  }>({
    result: [],
    nextOffset: null,
    done: false,
  });

  const handlePress = async () => {
    try {
      if (contacts.done) {
        console.log('Fetched all contacts.');
        return;
      }

      const response = await fetchContacts({
        size: 10,
        offset: contacts.nextOffset ?? 0,
        query: { contains: 'Kim' },
      });
      setContacts((prev) => ({
        result: [...prev.result, ...response.result],
        nextOffset: response.nextOffset,
        done: response.done,
      }));
    } catch (error) {
      if (error instanceof FetchContactsPermissionError) {
        console.log('No contact read permission');
      }
      console.error('Failed to fetch contacts:', error);
    }
  };

  return (
    <div>
      {contacts.result.map((contact, index) => (
        <span key={index}>
          {contact.name}: {contact.phoneNumber}
        </span>
      ))}
      <input
        type="button"
        value={contacts.done ? 'Fetched all contacts.' : 'Fetch next contacts'}
        disabled={contacts.done}
        onClick={handlePress}
      />
      <input
        type="button"
        value="Check permission"
        onClick={async () => {
          const permission = await fetchContacts.getPermission();
          alert(permission);
        }}
      />
      <input
        type="button"
        value="Request permission"
        onClick={async () => {
          const permission = await fetchContacts.openPermissionDialog();
          alert(permission);
        }}
      />

  );
}

React Native

import { ContactEntity, fetchContacts, FetchContactsPermissionError } from '@apps-in-toss/framework';
import { useState } from 'react';
import { Alert, Button, Text, View } from 'react-native';

function ContactsList() {
  const [contacts, setContacts] = useState<{
    result: ContactEntity[];
    nextOffset: number | null;
    done: boolean;
  }>({
    result: [],
    nextOffset: null,
    done: false,
  });

  const handlePress = async () => {
    try {
      if (contacts.done) {
        console.log('Fetched all contacts.');
        return;
      }

      const response = await fetchContacts({
        size: 10,
        offset: contacts.nextOffset ?? 0,
        query: { contains: 'Kim' },
      });
      setContacts((prev) => ({
        result: [...prev.result, ...response.result],
        nextOffset: response.nextOffset,
        done: response.done,
      }));
    } catch (error) {
      if (error instanceof FetchContactsPermissionError) {
        console.log('No contact read permission');
      }
      console.error('Failed to fetch contacts:', error);
    }
  };

  return (
    <View>
      {contacts.result.map((contact, index) => (
        <Text key={index}>
          {contact.name}: {contact.phoneNumber}
        </Text>
      ))}
      <Button
        title={contacts.done ? 'Fetched all contacts.' : 'Fetch next contacts'}
        disabled={contacts.done}
        onPress={handlePress}
      />
      <Button
        title="Check Permission"
        onPress={async () => {
          const permission = await fetchContacts.getPermission();
          Alert.alert(permission);
        }}
      />
      <Button
        title="Request permission"
        onPress={async () => {
          const permission = await fetchContacts.openPermissionDialog();
          Alert.alert(permission);
        }}
      />
    </View>
  );
}