Messages

A Message is a dictionary sent over the Session for immediate delivery. It only works while the Watch is reachable: the Watch app is running and in range. Check isWatchReachable before sending. To send data that waits until the Watch app can take it, use Application Context or User Info instead.

Messages travel both ways:

• Outbound (iPhone → Watch): sendMessage asks for a Reply, and sendMessageWithoutReply doesn't.
• Inbound (Watch → iPhone): onMessageReceived fires for a Message that doesn't ask for a Reply, and onMessageWithReply fires for one that does.

A Message's values must be ones WatchConnectivity can carry: strings, numbers, booleans, arrays and nested objects. Anything else fails with ERR_PAYLOAD_UNSUPPORTED_TYPES. To send raw bytes, use Data Messages.

sendMessageCopy Anchor Link

sendMessage<T extends MessagePayload, R extends MessagePayload>(message: T): Promise<R>

Sends a Message to the Watch and waits for its Reply.

The Watch app must receive it with a reply handler and call it, in session(_:didReceiveMessage:replyHandler:). If it never replies, the Promise rejects with ERR_MESSAGE_REPLY_TIMED_OUT.

Type parameters

MessagePayload is Record<string, any>.

Parameters

Returns Promise<R>, which resolves with the Watch's Reply.

Throws (the Promise rejects with):

WatchConnectivity can fail with other codes too. See Error codes for the full list.

Example

import RnWatchConnect, { type WatchConnectErrorCode } from "rn-watch-connect";

type Ping = { ping: number };
type Pong = { pong: number };

try {
  const reply = await RnWatchConnect.sendMessage<Ping, Pong>({ ping: 1 });
        
const reply: Pong
  console.log(reply.pong);
} catch (error) {
  const code = (error as { code?: WatchConnectErrorCode }).code;
  if (code === "ERR_WATCH_NOT_REACHABLE") {
    // Try again when onReachabilityChanged says the Watch is reachable.
  }
}

sendMessageWithoutReplyCopy Anchor Link

sendMessageWithoutReply<T extends MessagePayload>(message: T): Promise<void>

Sends a Message to the Watch without asking for a Reply. The Watch app receives it in session(_:didReceiveMessage:).

Type parameters

Parameters

Returns Promise<void>, which resolves once the Message is handed to the Session.

Throws (the Promise rejects with):

Its error message starts with Expo's prefix, "Calling the 'sendMessageWithoutReply' function has failed", so match on code.

Example

import RnWatchConnect from "rn-watch-connect";

if (RnWatchConnect.isWatchReachable) {
  await RnWatchConnect.sendMessageWithoutReply({ score: 42 });
}

onMessageReceivedCopy Anchor Link

onMessageReceived: (message: MessagePayload) => void

Fires when an Inbound Message arrives that doesn't ask for a Reply. The listener gets the Message itself.

Example

import { useEventListener } from "expo";
import RnWatchConnect from "rn-watch-connect";

export function ScoreListener() {
  useEventListener(RnWatchConnect, "onMessageReceived", (message) => {
    console.log("Score from the Watch:", message.score);
  });
  return null;
}

Outside a component, use addListener, and call remove() on the subscription when you're done:

import RnWatchConnect from "rn-watch-connect";

const subscription = RnWatchConnect.addListener("onMessageReceived", (message) => {
  console.log(message);
});

subscription.remove();

onMessageWithReplyCopy Anchor Link

onMessageWithReply: (event: MessageWithReplyEvent) => void

Fires when an Inbound Message arrives that asks for a Reply. Answer it by calling the event's Reply function, reply.

Event

Each Message takes one Reply:

• If several listeners get the same Message, the first reply call wins. Later calls reject.
• A Message can stop waiting for its Reply, for example when its last listener is removed. Calling reply after that rejects.

reply throws (its Promise rejects with):

Example

import { useEventListener } from "expo";
import RnWatchConnect from "rn-watch-connect";

export function PingResponder() {
  useEventListener(RnWatchConnect, "onMessageWithReply", ({ message, reply }) => {
    if ("ping" in message) {
      reply({ pong: message.ping });
    }
  });
  return null;
}

replyToMessageCopy Anchor Link

replyToMessage(replyId: string, reply: MessagePayload): Promise<void>

Sends the Reply to an Inbound Message, using the replyId from its onMessageWithReply event.

Parameters

Returns Promise<void>, which resolves once the Reply is sent.

Throws (the Promise rejects with):

Its error message starts with Expo's prefix, "Calling the 'replyToMessage' function has failed", so match on code.

Moving to reply

// Before (deprecated)
useEventListener(RnWatchConnect, "onMessageWithReply", ({ message, replyId }) => {
  RnWatchConnect.replyToMessage(replyId, { pong: message.ping });
});

// After
useEventListener(RnWatchConnect, "onMessageWithReply", ({ message, reply }) => {
  reply({ pong: message.ping });
});