A small, typed client for the WhatsApp Cloud API (Meta Graph API), focused on sending messages and handling common interactive patterns.
- ESM package (
"type": "module") - Works in Node.js (fetch-enabled) and Bun
- TypeScript-first API
pnpm add @nivalis/whatsapp-clientPeer dependency: typescript@^5.
import { WhatsAppClient } from '@nivalis/whatsapp-client';
const client = new WhatsAppClient({
phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
});
await client.sendMessage('15551234567', 'Hello from WhatsApp Cloud API');export type WhatsAppClientConfig = {
phoneNumberId: string;
accessToken: string;
};The client sends requests to:
https://graph.facebook.com/v21.0/{phoneNumberId}/messagesfor messaging operationshttps://graph.facebook.com/v21.0/{mediaId}for media lookups
await client.sendMessage('15551234567', 'Hi!');import { REACTION_EMOJIS } from '@nivalis/whatsapp-client';
await client.reactToMessage('15551234567', 'wamid.HBgLM...', REACTION_EMOJIS.SUCCESS);Remove a reaction:
await client.removeReaction('15551234567', 'wamid.HBgLM...');await client.sendInteractiveButtons('15551234567', 'Pick one:', [
{ id: 'choice_a', title: 'A' },
{ id: 'choice_b', title: 'B' },
]);await client.sendListMessage(
'15551234567',
'Choose a plan:',
'View plans',
[
{
title: 'Plans',
rows: [
{ id: 'basic', title: 'Basic', description: '$9/mo' },
{ id: 'pro', title: 'Pro', description: '$19/mo' },
],
},
],
);Notes:
- Max 10 sections
- Max 10 rows per section
const file = await client.downloadMedia('1234567890');
// `file` is a BufferIf the Meta API responds with a non-2xx status, the client throws an error including the HTTP status and response body.
pnpm install
pnpm lint
pnpm test
pnpm buildUseful scripts:
pnpm lint/pnpm lint:fix(Biome)pnpm test(Bun)pnpm build(zshy)pnpm ts(typecheck)
MIT