# WhatsApp

Canonical HTML: https://p-hatan.com/deeplink-x/apps/whatsapp/

DeeplinkX 1.5.8.

## Platforms and setup

Native platforms: **ios, android, windows, macos**.

- chatByUsername expects the recipient bare username without @; the package does not normalize or validate it.
- Username availability is controlled by WhatsApp rollout and recipient setup. Username-key prompts are handled inside WhatsApp; DeeplinkX has no username-key parameter.
- The destination app manages recipient resolution and the composer; the user sends the message.

## Public actions

### WhatsApp.open


```dart
factory WhatsApp.open({final bool fallbackToStore = false})
```

Launch with `DeeplinkX.launchApp`. Native platforms: **ios, android, windows, macos**. Action web fallback: **available**. Store-fallback flag: **supported; opt in explicitly**.

| Parameter | Type | Required | Default |
| --- | --- | --- | --- |
| `fallbackToStore` | `bool` | No | `false` |

[Exact source](https://github.com/DeepLinkX/DeeplinkX/blob/00d9d2c7c1affe4e2ee459a01afeba82a1480eac/lib/src/apps/downloadable_apps/whatsapp.dart#L22)

### WhatsApp.chat


```dart
static WhatsAppChatAction chat({ required final String phoneNumber, final String? message, final bool fallbackToStore = false, })
```

Launch with `DeeplinkX.launchAction`. Native platforms: **ios, android, windows, macos**. Action web fallback: **available**. Store-fallback flag: **supported; opt in explicitly**.

| Parameter | Type | Required | Default |
| --- | --- | --- | --- |
| `phoneNumber` | `String` | Yes | — |
| `message` | `String?` | No | — |
| `fallbackToStore` | `bool` | No | `false` |

[Exact source](https://github.com/DeepLinkX/DeeplinkX/blob/00d9d2c7c1affe4e2ee459a01afeba82a1480eac/lib/src/apps/downloadable_apps/whatsapp.dart#L78)

### WhatsApp.chatByUsername


```dart
static WhatsAppChatByUsernameAction chatByUsername({ required final String username, final String? message, final bool fallbackToStore = false, })
```

Launch with `DeeplinkX.launchAction`. Native platforms: **ios, android, windows, macos**. Action web fallback: **available**. Store-fallback flag: **supported; opt in explicitly**.

| Parameter | Type | Required | Default |
| --- | --- | --- | --- |
| `username` | `String` | Yes | — |
| `message` | `String?` | No | — |
| `fallbackToStore` | `bool` | No | `false` |

[Exact source](https://github.com/DeepLinkX/DeeplinkX/blob/00d9d2c7c1affe4e2ee459a01afeba82a1480eac/lib/src/apps/downloadable_apps/whatsapp.dart#L95)

### WhatsApp.shareText


```dart
static WhatsAppShareTextAction shareText({ required final String text, final bool fallbackToStore = false, })
```

Launch with `DeeplinkX.launchAction`. Native platforms: **ios, android, windows, macos**. Action web fallback: **available**. Store-fallback flag: **supported; opt in explicitly**.

| Parameter | Type | Required | Default |
| --- | --- | --- | --- |
| `text` | `String` | Yes | — |
| `fallbackToStore` | `bool` | No | `false` |

[Exact source](https://github.com/DeepLinkX/DeeplinkX/blob/00d9d2c7c1affe4e2ee459a01afeba82a1480eac/lib/src/apps/downloadable_apps/whatsapp.dart#L115)


## Provider setup and examples
## Overview
DeeplinkX provides support for WhatsApp deeplinks, allowing you to open the WhatsApp app, start chats with phone numbers or usernames, and share content.

## Available Actions

### Launch WhatsApp App
```dart
final deeplinkX = DeeplinkX();

// Simple launch
await deeplinkX.launchApp(WhatsApp.open());

// Launch with store fallback if not installed
await deeplinkX.launchApp(WhatsApp.open(fallbackToStore: true));

// Launch with fallback disabled
await deeplinkX.launchApp(WhatsApp.open(), disableFallback: true);
```

### Launch Chat with Phone Number Action
```dart
final deeplinkX = DeeplinkX();

// Simple action
await deeplinkX.launchAction(WhatsApp.chat(
  phoneNumber: '1234567890',
  message: 'Hello!', // Optional
));

// Action with store fallback if not installed
await deeplinkX.launchAction(
  WhatsApp.chat(
    phoneNumber: '1234567890',
    message: 'Hello!', // Optional
    fallbackToStore: true,
  ),
);

// Action with fallback disabled
await deeplinkX.launchAction(
  WhatsApp.chat(
    phoneNumber: '1234567890',
    message: 'Hello!', // Optional
  ),
  disableFallback: true,
);
```

### Launch Chat with Username Action

```dart
final deeplinkX = DeeplinkX();

// Replace this illustrative username with the recipient's exact username.
await deeplinkX.launchAction(WhatsApp.chatByUsername(
  username: 'example_user', // Without the leading @
  message: 'Hello!', // Optional; prefills the composer without sending
));

// Use the existing platform-specific store fallback.
await deeplinkX.launchAction(WhatsApp.chatByUsername(
  username: 'example_user',
  fallbackToStore: true,
));

// Attempt only the native link, without store or web fallback.
await deeplinkX.launchAction(
  WhatsApp.chatByUsername(username: 'example_user'),
  disableFallback: true,
);
```

Supply a bare username without `@`. DeeplinkX preserves it as supplied without normalization or username validation. WhatsApp determines whether the username exists and is available to contact. A null message omits the `text` query parameter; an explicitly empty message retains `text=`.

This action inherits WhatsApp's existing Android, iOS, macOS, and Windows support and uses the same platform configuration and fallback flow as phone chats. Usernames are rolling out gradually, so the recipient's reserved username may not be active yet. WhatsApp may ask for the recipient's username key; obtain that key from the recipient and enter it inside WhatsApp. DeeplinkX does not accept or append a username-key parameter.

See [username chats](#username-chats) for recipient setup and username-key behavior.

### Launch Share Text Action
```dart
final deeplinkX = DeeplinkX();

// Simple action
await deeplinkX.launchAction(WhatsApp.shareText(
  text: 'Check out this cool Flutter package: https://pub.dev/packages/deeplink_x',
));

// Action with store fallback if not installed
await deeplinkX.launchAction(
  WhatsApp.shareText(
    text: 'Check out this cool Flutter package: https://pub.dev/packages/deeplink_x',
    fallbackToStore: true,
  ),
);

// Action with fallback disabled
await deeplinkX.launchAction(
  WhatsApp.shareText(
    text: 'Check out this cool Flutter package: https://pub.dev/packages/deeplink_x',
  ),
  disableFallback: true,
);
```

## Platform-Specific Configuration

### iOS
Add the following to your `ios/Runner/Info.plist`:
```xml
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>whatsapp</string>
    <string>itms-apps</string>
</array>
```

### Android
Add the following to your `android/app/src/main/AndroidManifest.xml` inside the `<queries>` tag:
```xml
<queries>
    <!-- For WhatsApp app -->
    <package android:name="com.whatsapp" />
    
    <!-- For Play Store fallback (if using fallbackToStore) -->
    <package android:name="com.android.vending" />
    
    <!-- For web fallback (required) -->
    <intent>
        <action android:name="android.intent.action.VIEW" />
        <data android:scheme="https" />
    </intent>
</queries>
```

### macOS
Add the following to your `macos/Runner/Info.plist`:
```xml
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>whatsapp</string>
    <string>macappstore</string>
</array>
```

## URL Schemes

### Native App URI
WhatsApp uses the following URI scheme for native app deeplinks:

- `whatsapp://` - Base URI for WhatsApp app

Examples:
- `whatsapp://` - Opens the WhatsApp app
- `whatsapp://send?phone=1234567890&text=Hello%20World` - Opens a chat with the specified phone number
- `whatsapp://send?username=example_user` - Targets a chat by username
- `whatsapp://send?username=example_user&text=Hello+World` - Targets a username chat with pre-filled text
- `whatsapp://send?text=Hello%20World` - Opens WhatsApp with pre-filled text to share

### Web Fallback URI
When the WhatsApp app is not installed, DeeplinkX will fall back to these web URLs:

- `https://wa.me` - Base URI for WhatsApp web

Examples:
- `https://wa.me` - Opens WhatsApp web
- `https://wa.me/1234567890` - Opens a chat with the specified phone number on WhatsApp web
- `https://wa.me/example_user` - Opens the username click-to-chat link
- `https://wa.me/example_user?text=Hello+World` - Username web fallback with an optional message parameter; WhatsApp controls the composer
- `https://wa.me?text=Hello%20World` - Opens WhatsApp web with pre-filled text

### Username chats

Supply the recipient's bare username without `@`. Username availability depends on WhatsApp's rollout and recipient setup. WhatsApp may ask for a username key; DeeplinkX does not accept or bypass that key. WhatsApp controls recipient resolution and the composer, and the user sends the message.

- [WhatsApp: contact someone by username](https://faq.whatsapp.com/1561101675623754/?cms_platform=web&helpref=faq_content)
- [WhatsApp: click to chat](https://faq.whatsapp.com/5913398998672934)

## Supported Fallback Stores
When the WhatsApp app is not installed, DeeplinkX can redirect users to download WhatsApp from the following app stores:

- iOS App Store
- Google Play Store
- Microsoft Store
- Mac App Store

To enable fallback to app stores, use the `fallbackToStore` parameter:

```dart
final deeplinkX = DeeplinkX();
await deeplinkX.launchApp(WhatsApp.open(fallbackToStore: true));
```

## Fallback Behavior
DeeplinkX follows this sequence when handling WhatsApp deeplinks:

1. First, it attempts to launch the WhatsApp app if it's installed on the device using the `whatsapp://` URL scheme.
2. If the app is not installed or its native link cannot be launched and `fallbackToStore` is set to `true`, it attempts the matching iOS App Store, Google Play Store, Mac App Store, or Microsoft Store listing.
3. If store fallback is disabled or cannot launch, it opens the action's web fallback in the default browser. Username chats use `https://wa.me/<username>` with `text` included when a message is supplied.
4. You can disable all fallbacks by setting `disableFallback: true` in the launch methods.

## Fallback Support for Actions

| Action         | Store Fallback | Web Fallback |
| -------------- | -------------- | ------------ |
| open           | ✅              | ✅            |
| chat           | ✅              | ✅            |
| chatByUsername | ✅              | ✅            |
| shareText      | ✅              | ✅            |

## Check If WhatsApp Is Installed

```dart
final deeplinkX = DeeplinkX();
final isInstalled = await deeplinkX.isAppInstalled(WhatsApp());
```