@heykoala/whatsapp-client-sdk

React SDK for embedding WhatsApp business messaging UI — chat inbox, template management, bulk campaigns, number onboarding, and delivery reports — backed by the hk-whatsapp API. Modular and tree-shakeable: one shared core plus per-feature subpath exports, so an app bundles only the modules it imports. Zero runtime dependencies; React is the only peer.

Install

npm install @heykoala/whatsapp-client-sdk

Quick start

import { WhatsAppProvider } from '@heykoala/whatsapp-client-sdk';
import { ChatWindow } from '@heykoala/whatsapp-client-sdk/chat';
import '@heykoala/whatsapp-client-sdk/styles.css';          // base tokens (once)
import '@heykoala/whatsapp-client-sdk/chat/styles.css';     // one CSS per module

<WhatsAppProvider
  config={{ apiUrl: 'https://api.example.com/api/v1', defaultHeaders: { 'X-API-Key': 'wbk_…' } }}
  theme={{ colorPrimary: '#25D366' }}
>
  <ChatWindow />
</WhatsAppProvider>;

Wrap once, import the module you need, drop in the component. Components scope themselves to the app-wide active number managed by the provider — no per-component wiring.

Modules & components

core (.)

• WhatsAppProvider / useWhatsApp — context: API client, theme, numbers, active number
• createApiClient, useResource, useMutation, ApiError — typed REST access
• Spinner, SearchInput, TemplatePreview, Modal — shared primitives
• Theming (themeToVars, --wa-* tokens) and validation helpers

chat (./chat)

• ChatWindow — full inbox (conversation list + thread + composer)
• ConversationList, MessageList, MessageBubble, Composer, TemplatePicker
• Hooks: useConversations, useConversation (alias useMessages), useSendTemplate, useMediaUrl

templates (./templates)

• TemplateList, TemplateBuilder, TemplatePreview
• Hooks: useTemplates, useCreateTemplate, useDeleteTemplate, useUploadMedia

campaigns (./campaigns)

• CampaignBuilder, CampaignList — build and launch bulk template sends
• Hooks: useCampaigns, useCampaign, useSaveCampaign, useSendCampaign, useDeleteCampaign

onboarding (./onboarding)

• AccountManager, AccountCard, WhatsAppSignupButton — connect numbers via Meta Embedded Signup
• Hook: useEmbeddedSignup

reports (./reports)

• ReportsDashboard, CampaignReport, CampaignReportList, DirectMessageReport
• Hooks: useCampaignReport, useCampaignMessages, useReportCampaigns, useMessageReports

Theming

Every style is a --wa-* CSS variable. Override them in your own CSS or pass a theme object to the provider.

Changelog

See CHANGELOG.md. The package follows Semantic Versioning.