Contacts

A Contact is a known user record that Helply can associate across conversations once you identify them.

Use Contacts when you want the widget to recognize a visitor as a real user in your system, and you want attributes that are verified by your backend (not editable in the browser).

Secure Attributes are attributes you mark Secure in the Attributes schema and then populate via identify (JWT) (link to "How to use them" in the Quickstart Contacts).

You can use Secure Attributes in Actions and Guidance.

How to create a contact

Step 1: Get the signing secret

Go to: Settings → API and copy the API key contacts_api_key).

Store it as a server-side secret (e.g. CONTACTS_API_KEY).

Step 2 (your server-side): generate the identity token

You need to securely generate identity token that you will pass to your frontend client.

The JWT Identity token requires this payload:

- user_id (required - any id that you can use to identify users from your system - supports both numbers and strings)

- contact_attributes (optional; put secure attributes here)

JavaScriptimport jwt from 'jsonwebtoken';
// server-side example of JWT token generation
app.get('/api/helply-token', authenticateUser, (req, res) => {
    const payload = {
        user_id: req.user.id,
        contact_attributes: {
            stripe_customer_id: req.user.stripeCustomerId,
            pricing_plan: req.user.plan,
        },
    };

    const token = jwt.sign(payload, process.env.CONTACTS_API_KEY, {
        algorithm: 'HS256',
        expiresIn: '1h',
    });
    res.json({ token });
});

Step 3 (client-side): Identify the user

Using the token you acquired from your backend, run identify call

JavaScriptwindow.addEventListener('helplyAgentLoaded', async function () {
    // load token from your backend
    const { token } = await fetch('/api/helply-token').then((r) => r.json());
    await window.helplyAgentWidget?.identify({
        token,
        // Optional: Insecure Attributes that are visible to the AI agent but are NOT 
        // stored as a contact. 
        user_metadata: {
            locale: 'en-US',
        },
    });
});