findContact

Looks up CRM contacts by phone number. This powers call pop, call logging, SMS/fax logging, and manual refresh.

Signature

async function findContact({
  user,
  authHeader,
  phoneNumber,
  overridingFormat,
  isExtension,
  proxyConfig,
  tracer,
  isForceRefreshAccountData
}) {
  return {
    successful: true,
    matchedContactInfo: [],
    returnMessage: null,
    extraDataTracking: {}
  };
}

Input

Field	Description
user	Connected CRM user.
authHeader	Prepared CRM auth header.
phoneNumber	Phone number to search, usually in E.164 format.
overridingFormat	Comma-separated phone formats from advanced user settings. Convert and search these if the CRM requires exact formatting.
isExtension	Indicates an internal extension-number lookup when extension-number logging is enabled.
proxyConfig	Proxy configuration when applicable.
tracer	Debug tracer when the request has is-debug: true.
isForceRefreshAccountData	True when the caller wants to bypass cached contact data.

Return

Field	Description
successful	true when lookup completed, even if no contact was found.
matchedContactInfo	Array of contacts. Return [] for no matches.
returnMessage	Optional UI message. If omitted and no contact is found, core supplies a default warning.
extraDataTracking	Optional analytics/tracing data, such as rate-limit state or { isCached: true }.

Each contact can include:

Field	Description
id	CRM contact ID.
name	Contact display name.
phone	Matched phone number.
type	Contact type used by contactPageUrl and CRM-specific logic.
title, company, email, mostRecentActivityDate	Optional display/search metadata.
additionalInfo	Object keyed by manifest additionalFields[].const values. Use this for contact-dependent options such as matters, deals, or opportunities.
isNewContact	Use only for the special "Create new contact..." option. Core does not cache contacts marked this way.

Caching

Core caches non-new contact matches by RingCentral account, platform, and phone number. A forced refresh bypasses the cache and removes stale cached data when the CRM returns no contacts.

Create-Contact Option

If you want the UI to offer contact creation, append:

matchedContactInfo.push({
  id: 'createNewContact',
  name: 'Create new contact...',
  isNewContact: true,
  additionalInfo: null
});

Do not create contacts inside findContact just because no match was found. Return an empty list and let the user or auto-logging rules trigger createContact.

Reference

Template

const axios = require('axios');

async function findContact({ user, authHeader, phoneNumber, overridingFormat, isExtension }) {

    console.log(`phone number: ${phoneNumber}`)
    console.log(`is extesnion number? ${isExtension}`)
    const numberToQueryArray = [];
    if (isExtension) {
        numberToQueryArray.push(phoneNumber);
    }
    else {
        numberToQueryArray.push(phoneNumber.replace(' ', '+'));
    }

    const storedContacts = require('../mockContacts.json');
    const matchedContactInfo = [];
    const matchedContacts = storedContacts.filter(contact => contact.phone === phoneNumber);
    if (matchedContacts?.length > 0) {
        console.log(`found contacts... \n\n${JSON.stringify(matchedContacts, null, 2)}`);
        matchedContactInfo.push(...matchedContacts);
    }
    //------------------------------------------------------
    //--- CHECK: In console, if contact info is printed ----
    //------------------------------------------------------

    //--------------------------------------
    //--- TODO: Add CRM API call here ------
    //--- TODO: Delete above mock JSON -----
    //--------------------------------------
    // for (var numberToQuery of numberToQueryArray) {
    //     const personInfo = await axios.get(
    //         `https://api.crm.com/contacts?query=number:${numberToQuery}`,
    //         {
    //             headers: { 'Authorization': authHeader }
    //         });
    //     if (personInfo.data.length > 0) {
    //         for (var result of personInfo.data) {
    //             foundContacts.push({
    //                 id: result.id,
    //                 name: result.name,
    //                 type: result.type,
    //                 phone: numberToQuery,
    //                 additionalInfo: null
    //             })
    //         }
    //     }
    // }

    // If you want to support creating a new contact from the extension, below placeholder contact should be used
    matchedContactInfo.push({
        id: 'createNewContact',
        name: 'Create new contact...',
        additionalInfo: null,
        isNewContact: true
    });
    return {
        successful: true,
        matchedContactInfo,
        returnMessage: {
            messageType: 'success',
            message: 'Successfully found contact.',
            detaisl: [
                {
                    title: 'Details',
                    items: [
                        {
                            id: '1',
                            type: 'text',
                            text: `Found ${matchedContactInfo.length} contacts`
                        }
                    ]
                }
            ],
            ttl: 3000
        }
    };  //[{id, name, phone, additionalInfo}]
}

module.exports = findContact;