WhatsApp

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
• WhatsApp.chat
• WhatsApp.chatByUsername
• WhatsApp.shareText

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

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

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

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

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

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

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

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 for recipient setup and username-key behavior.

Launch Share Text Action

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:

<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:

<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:

<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
• WhatsApp: click to chat

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:

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

Check If WhatsApp Is Installed

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