JavaScript API.

The JavaScript API is used to interact with the widget and the AI. Below is a list of all available methods and their usage.

• Initialize Widget (init)
• Request Data from the AI (ask)
• Open Chat (open)
• Close Chat (close)
• Update Consent Status (consent)
• Update Options (update)

The init method is used to initialize the widget with your project settings and user data.

h2h('init', {
    project_id: '{YOUR_PROJECT_ID}',
    contact: {
        name: 'John Doe',
        email: '[email protected]',
        identifier: 'user-example-123',
        hash: '{USER_HASH}',
        metadata: {
            hash: '{METADATA_HASH}',
            user_active: true,
            company_name: 'Example Company',
        }
    }
    // ... include settings, theme, and text objects here
});

Replace {YOUR_PROJECT_ID} with your project ID found at Settings > Widget. Replace {USER_HASH} and {METADATA_HASH} with verification hashes which can be generated by following the hash generation guide.

Your can include any JavaScript options in the init method to customize the widget's appearance, behavior, and much more.

The ask method is used to request data from the AI. This can be used to ask questions, retrieve user details and much more.

const response = await h2h('ask', {
    messages: [
        'Please provide a new title for this site which would be more suitable for this user.',
        'Take into account their browsing history and likely goals.',
        'You can completely rewrite the title if you think it would be more effective.',
        'Here is the current title; "Let AI Take Charge of Your Website."',
        'Only respond with the new title.',
    ]
});

console.log('AI Answer:', response.answer);

The messages parameter is an array of messages to send to the AI. It can be any type of question you'd like to ask about the current user - such as where they came from or what product they might be looking for on your site. Be as explicit as possible to get the best results.

This call is processed asynchronously. The response contains the completed answer.

We also support requesting limited structured data by providing params as an array of expected fields to return. Currently these are limited to strings, but we plan to support more complex data types in the future. This is often used for populating data during onboarding, or personalizing the user experience.

const response = await h2h('ask', {
    messages: ['Retrieve user details'],
    params: ['company_name', 'job_title', 'location']
});

console.log('Company:', response.params.company_name);
console.log('Job:', response.params.job_title);
console.log('Location:', response.params.location);
console.log('Metadata:', response.metadata);

This call is processed asynchronously. The response contains completed params along with any metadata that was returned.

Opens the chat interface for the user to start or continue a conversation.

h2h('open');

If an AI is enabled, the chat interface will open with the AI greeting the user. If no AI is enabled, the chat interface will open with the user's previous conversation history.

Close the chat interface, if it is open.

h2h('close');

When initializing the widget you must first set await_consent, in order to later use the consent method to update the user's consent status.

h2h('init', {
    project_id: '{YOUR_PROJECT_ID}',
    settings: {
        await_consent: true,
    }
});

Once the user provides consent (such as through a cookie banner), you can now update the user's consent status. This will start the widget and any related services. Until the user provides consent, the widget will remain inactive and no data will be processed.

h2h('consent', {
    provided: true,
});

You can also later revoke consent if needed. This will immediately stop the widget and any related services.

h2h('consent', {
    provided: false,
});

Update any of the widget's settings, theme, text, or contact details after initialization.

h2h('update', {
    contact: {
        // ... contact details goes here
    }
    settings: {
        // ... new setting goes here
    },
    theme: {
        // ... updated theme goes here
    },
    text: {
        // ... updated text goes here
    }
});

A full list of fields can be found on the JavaScript options page.