# Custom events

Custom events are *synthetic events* in Javascript that can be dispatched to our SDK.

Use custom events to communicate with Didomi custom elements to wrap your code and handle all logic, analytics and API requests.

* [didomi:send-authentication](#didomi-send-authentication)
* [didomi:verify-otp-code](#didomi-verify-otp-code)
* [didomi:set-pending-consents](#didomi-set-pending-consents)
* [didomi:save-pending-consents](#didomi-save-pending-consents)
* [didomi:set-consents](#didomi-set-consents)

#### didomi:send-authentication

To request end-user authentication through the Didomi SDK and send an email to your end-user (via either Magic Link or One-Time Password code) dispatch the `didomi:send-authentication` custom event. Set the email address provided by the end-user to `detail.value`.

Note that our Headless widget will use the default authentication provider of your organization. To use a different provider, you can [define a provider](/api-and-platform/widgets/privacy-widgets/authentication/manage-authentication-providers.md#manage-authentication-within-a-widget) at widget level.

{% hint style="warning" %}
`didomi:send-authentication` custom event needs to be dispatched from an element within the `didomi-auth-headless` custom element.
{% endhint %}

```javascript
new CustomEvent("didomi:send-authentication", {
      detail: {
        value: email,
      },
      bubbles: true,
      composed: true,
    });
```

#### didomi:verify-otp-code

*<mark style="color:blue;">This event needs the previous event to work properly as the</mark>* <mark style="color:blue;">`send-authentication`</mark> *<mark style="color:blue;">event will allow email address storage in local storage that is required to verify the code.</mark>*

If your widget is using a One-Time Password provider, you need to verify the code received by the end-user. To verify the code, dispatch the `didomi:verify-otp-code` custom event. Set the code provided by the end-user to `detail.value`.

{% hint style="warning" %}
`didomi:verify-otp-code` custom event needs to be dispatched from an element within the `didomi-auth-headless` custom element.
{% endhint %}

```json
new CustomEvent("didomi:verify-otp-code", {
      detail: {
        value: otpCode,
      },
      bubbles: true,
      composed: true,
    });
```

#### didomi:set-pending-consents

To set end-user pending consents in your web application state, dispatch the `didomi:set-pending-consents` custom event.

When setting a purpose, the `detail` object must contain the `purposeId` and the corresponding `value` (true or false). When setting a preference, the `detail` object must contain the `purposeId`, `preferenceId`, and the selected `value`.

{% hint style="warning" %}
Custom event `didomi:set-pending-consents` should be dispatched from an element placed within the `didomi-pending-consent-receiver` wrapper.
{% endhint %}

```javascript
new CustomEvent("didomi:set-pending-consents", {
      // If used for Purposes
      detail: {
        purposeId,
        value: true/false,
      },
      // If used for Preference values
      detail: {
        purposeId,
        preferenceId,
        value: "asdf,ghjk,bvcx", // list of enabled values as string
      },
      bubbles: true,
      composed: true,
    });
```

#### didomi:save-pending-consents

To save end-user pending consents using the Didomi SDK, dispatch the `didomi:save-pending-consents` custom event.

{% hint style="warning" %}
Custom event `didomi:save-pending-consents`should be dispatched from an element placed within the `didomi-pending-consent-receiver` wrapper.
{% endhint %}

```javascript
new CustomEvent("didomi:save-pending-consents", {
      detail: {
        // You can pass optional metadata object
        metadata: {},
        // You can pass optional userMetadata object
        userMetadata: {},
      },
      bubbles: true,
      composed: true,
    });
```

#### didomi:set-consents

To save end-user consent upon end-user click through our SDK, dispatch the `didomi:set-consents` custom event.

When saving a purpose, the `detail` object should include the `purposeId` and the corresponding `value` (true or false). When saving a preference, the `detail` object should include the `purposeId`, `preferenceId`, and the selected `value`.

Custom event `didomi:set-consents` should be dispatched from an element placed within the `didomi-consent-receiver` wrapper.

```javascript
new CustomEvent("didomi:set-consents", {
      // If used for Purposes
      detail: {
        purposeId,
        value: true/false,
        // You can pass optional metadata object
        metadata: {},
        // You can pass optional userMetadata object
        userMetadata: {},
      },
      // If used for Preference values
      detail: {
        purposeId,
        preferenceId,
        value: "qFkQbPnT,gEhjHDk,sbvLLcx", // list of enabled values as string
        // You can pass optional metadata object
        metadata: {},
        // You can pass optional userMetadata object
        userMetadata: {},
      },
      bubbles: true,
      composed: true,
    });
```

*Note that the* `bubbles` *and* `composed` *options must be set to* `true` *to allow the event to bubble and trigger listeners outside of a shadow root, respectively.*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.didomi.io/api-and-platform/widgets/privacy-widgets/headless-widgets/custom-events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.