> For the complete documentation index, see [llms.txt](https://docs.webtonative.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.webtonative.com/javascript-apis/os-notification-sound/haptic-sound-apis.md).

# Haptic Sound Apis

Plays a custom sound alongside a haptic vibration effect, in one call.

Plays a custom sound — uploaded once via the WebToNative Dashboard — alongside a haptic vibration effect, in one call. Use this when an action should feel like a native alert *and* buzz at the same time (e.g. an order confirmation, an error state).

> This is the sound-specific side of `Haptics.trigger`. For plain haptic feedback without a sound — the full `effect` reference and `isHapticSupported` — see [Haptic Feedback](broken://pages/b6fa796e1b136fc7d88b5047fbb85590f1ffc502).

> Before calling this, upload the sound file via the Dashboard — see [Uploading the Sound File](broken://pages/a79c4542382c36e04c0f4f96d71228e854c27913#uploading-the-sound-file-dashboard) on the [OS Notification Sound](broken://pages/a79c4542382c36e04c0f4f96d71228e854c27913) page. Just want the sound alone, with no vibration? See [Sound.play](broken://pages/2d515e3fb3ebe549ba811c09f086c55f872cacd9).

> **Platform support:** Android and iOS.

***

## JavaScript API Reference

`Haptics.trigger` accepts an optional `soundName` alongside `effect`, so one call triggers both.

{% tabs %}
{% tab title="Plain Javascript" %}

```javascript
window.WTN.Haptics.trigger({
  effect: "impactMedium",
  soundName: "your_sound_name",
});
```

{% endtab %}

{% tab title="npm" %}

```javascript
import { trigger } from "webtonative/Haptics";

trigger({
  effect: "impactMedium",
  soundName: "your_sound_name",
});
```

{% endtab %}
{% endtabs %}

**Parameters:**

| Key         | Type     | Required | Description                                                                                                                                                                                                                   |
| ----------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `effect`    | `String` | No       | The vibration pattern to play. See [supported values](broken://pages/b6fa796e1b136fc7d88b5047fbb85590f1ffc502#trigger) on the Haptic Feedback page.                                                                           |
| `soundName` | `String` | No       | Name of an uploaded sound file to play alongside the haptic effect, using the exact same lookup rules as [`Sound.play`](broken://pages/2d515e3fb3ebe549ba811c09f086c55f872cacd9) — omit it to trigger the haptic effect only. |

> Internally this plays the sound through the same path as `Sound.play` — there's no behavioral difference between calling `Sound.play("x")` directly versus passing `soundName: "x"` here, other than the haptic effect firing at the same time.

***

## Common Patterns

### Sound Alone vs. Sound + Haptic

Reserve the combined call for actions that warrant both signals — use `Sound.play` alone for higher-frequency events where a vibration on every occurrence would be excessive:

```javascript
import { play } from "webtonative/Sound";
import { trigger } from "webtonative/Haptics";

function onChatMessageReceived() {
  // Sound only — this happens often, a haptic on every message would be excessive
  play("chat_ping");
}

function onOrderConfirmed() {
  // Sound + haptic together — a rarer, higher-significance event
  trigger({
    effect: "notificationSuccess",
    soundName: "order_confirmed",
  });
}
```

***

## Troubleshooting

* **Sound doesn't play (haptic effect still fires):** the sound lookup fails silently, same as [`Sound.play`](broken://pages/2d515e3fb3ebe549ba811c09f086c55f872cacd9#troubleshooting) — double-check the file was uploaded to the correct platform's field on the Dashboard, that you've rebuilt/reinstalled since uploading, and that the name (and extension, if you passed one) matches exactly.