Universal.Meta.WhatsApp.Client 1.0.0

Universal.Meta.WhatsApp.Client

A .NET client for WhatsApp's multi-device protocol.

Connect

Authentication state includes private identity keys and active Signal sessions. Store it in a private, persistent location and keep the JSON file together with its .keys.json sidecar.

var store = new FileWhatsAppAuthenticationStore(authenticationPath);
using var client = new WhatsAppClient(store);

client.ConnectionStateChanged += (_, e) => Console.WriteLine(e.State);
client.PairingQrCodeReceived += (_, e) => DisplayQrCode(e.Value);
client.MessageReceived += (_, e) => HandleMessage(e);

await client.ConnectAsync(cancellationToken);

Subscribe to events before connecting. A new account emits pairing QR codes and reaches Connected after linking. For phone-number pairing, call RequestPairingCodeAsync after ConnectAsync; the phone number must contain only the country code and subscriber number, such as 61400000000.

The cancellation token passed to ConnectAsync covers connection establishment only. Use DisconnectAsync or dispose the client to end an established connection.

Messages

Chat methods accept full WhatsApp JIDs. Phone-number chats use <country-code><number>@s.whatsapp.net; groups use the JID returned by the group APIs.

WhatsAppJid recipient = WhatsAppJid.FromPhoneNumber("61400000000");
string messageId = await client.SendTextMessageAsync(recipient, "hello", cancellationToken);

SendMediaMessageAsync encrypts and uploads a readable stream. DownloadMediaMessageAsync authenticates the media MAC and advertised hashes before writing plaintext to the supplied stream. The caller owns both streams.

Raw protobuf messages can be sent with SendMessageAsync. Raw protocol nodes are available through SendNodeAsync, NodeSent, and NodeReceived when a high-level operation is unavailable.

Extension points

• Implement IWhatsAppAuthenticationStore and IWhatsAppSignalKeyStore to use a database, secret store, or another persistence model.
• Set WhatsAppClientOptions.MediaHttpClient to control media HTTP transport, proxies, handlers, and lifetime.
• Set WhatsAppClientOptions.WebSocketFactory to replace the WebSocket transport. The factory must return a new IWhatsAppWebSocket for each connection attempt.
• Configure connection timeouts, client identity, synchronization, and protocol endpoint with WhatsAppClientOptions.

FileWhatsAppAuthenticationStore is the ready-to-use local implementation. Its directory permissions are the application's responsibility.