# whatsapp-cloud-inbox: a WhatsApp style inbox built on the Cloud API > whatsapp-cloud-inbox is a Next.js inbox for the official WhatsApp Cloud API, with template sending, interactive buttons, media, failed message markers and automatic enforcement of the 24 hour messaging window. It talks to the API through Kapso rather than Meta directly, and it stores the selected numbers in a cookie, so it is a reference application as much as a product. **gokapso/whatsapp-cloud-inbox** — Open source Inbox for the official WhatsApp Cloud API. - Repository: https://github.com/gokapso/whatsapp-cloud-inbox - Website: https://kapso.com/ - Stars: 796 · Forks: 136 - Language: TypeScript - License: MIT - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/gokapso-whatsapp-cloud-inbox ## A familiar inbox shape over an unfamiliar API whatsapp-cloud-inbox is an open source inbox for the official WhatsApp Cloud API, and the README describes it as a WhatsApp Web-style inbox built with Next.js for sending messages, templates and interactive buttons with a familiar user interface. That framing explains the design. The Cloud API is a low level messaging interface, and the hard part of putting it in front of a human is not the sending, it is the constraints. The application therefore spends most of its effort on making the policy visible: the 24 hour window is enforced automatically rather than left to the operator, templates are a first class flow rather than a fallback, and failed messages get a visible marker instead of disappearing. The feature list is short and concrete. Real-time messaging is done by auto-polling, which keeps conversations updated without a websocket. Template messages support the full parameter set, including header, body and buttons, with named and positional parameters detected automatically. Interactive button messages carry up to three custom actions. Media covers images, videos, documents and audio. And the interface itself has the read receipts, timestamps and message bubbles that people already know from WhatsApp. The audience is a developer who needs an inbox rather than a sender, so a support team, a product team testing a business account, or anyone learning the Cloud API by using it. ## Kapso sits between the app and the Cloud API The application does not call Meta directly. It uses Kapso, and the SDK dependency in package.json is @kapso/whatsapp-cloud-api at version 0.1.0. Kapso is a hosted service, the project homepage is kapso.com, and the setup steps in the README begin with creating an account at app.kapso.ai, connecting a WhatsApp number and obtaining a Kapso API key. That is a significant architectural decision for anyone considering adoption, and it cuts both ways. On one side it removes the part of the work that has nothing to do with the interface, which is the authentication, the phone number and business account management, and the business onboarding flow. On the other side, a customer conversation inbox now depends on a third party service being available, and the API key you deploy becomes the credential that matters. The environment variables show how much of the direct Cloud API shape is preserved. There is an optional WHATSAPP_API_URL for a custom API endpoint, an optional KAPSO_API_BASE_URL for the case where the platform API is on a different host, and a PHONE_NUMBER_ID and WABA_ID pair described as a backwards-compatible single-number fallback. In other words, the app can be pointed at a different host, but the routing still goes through the Kapso API shape rather than a raw Meta endpoint. ## Templates and the two step send flow Template messaging is where the application earns its keep, because templates are the mechanism WhatsApp requires for anything sent outside the customer service window and the details are easy to get wrong. The README describes full support for WhatsApp templates with parameters, covering the header, body and button parameters, with named and positional parameters detected automatically. That detection matters, because a template with two body parameters can be filled either as a map with keys or as an ordered list, and the UI has to know which shape the template expects before it can present fields. The interaction is a two-step flow: select the template, fill the parameters, send. That is a deliberate choice for a tool that anyone in a support team can use, since a single screen with a dropdown, a set of inputs and a send button is something a non-programmer can follow. Interactive messages cover the other half of the outbound story. These are button messages created without a template, with an optional header, a required body and between one and three buttons, each with a unique identifier and a title of at most 20 characters. The README frames them as ideal for quick replies, confirmations and menu selections, which is exactly the set of cases where a template would be overkill but a plain text message is not allowed. ## The 24 hour window is enforced in the interface WhatsApp's customer service window is the constraint that shapes every conversation in a Cloud API application, and whatsapp-cloud-inbox makes it a visible part of the user experience rather than a server side check. The README describes three states. Within 24 hours, regular messages can be sent freely. Outside 24 hours, the application switches to template-only mode with clear messaging about the restriction. And when there are no inbound messages at all, the user is guided towards sending templates instead. The 24-hour window enforcement is listed as a feature in its own right, which tells you the design intent: an operator should not be able to make the mistake of trying to send free-form text to a customer who has not messaged in, because that request would simply fail at the API. Converting a silent failure into a mode change in the interface is the difference between a support tool and a development sandbox. The same thinking shows up in the failed message indicators, which give visual feedback for delivery failures instead of leaving a message that looks sent but is not. ## Local setup: environment variables, port 4000 and a settings page The setup sequence in the README is three steps. Clone and install: ```bash git clone https://github.com/gokapso/whatsapp-cloud-inbox.git cd whatsapp-cloud-inbox npm install ``` Then create a .env file with the credentials and the optional overrides: ```bash KAPSO_API_KEY=your_kapso_api_key WHATSAPP_API_URL=https://api.kapso.ai/meta/whatsapp # Optional: custom API endpoint # Optional: only needed when your platform API is on a different host KAPSO_API_BASE_URL=https://api.kapso.ai # Optional: backwards-compatible single-number fallback PHONE_NUMBER_ID=your_phone_number_id WABA_ID=your_business_account_id ``` And run the development server: ```bash npm run dev ``` The application is then at http://localhost:4000, and there is a settings page at http://localhost:4000/settings where you choose which WhatsApp numbers the inbox tracks. The README explains the discovery flow: the app finds the PHONE_NUMBER_ID and WABA_ID values from Kapso using the API key, then stores the selected numbers in an HTTP-only cookie. That last detail is worth a note for anyone planning a deployment. The selection of numbers lives in a cookie rather than in a database, which is simple and stateless, and it also means the choice is per browser session rather than per user account. A deployment with several operators on shared machines would want to think about that. ## Next.js 15, React 19, Radix and Tailwind The dependency list in package.json describes a conventional modern React front end, and the versions are current enough to be worth noting. The framework is next at 15.5.9 with react and react-dom at 19.1.0. The UI primitives come from Radix UI, with separate packages for avatar, dialog, label, scroll area, separator and slot, and there is a components.json file in the repository root, which is the shadcn/ui configuration. Styling is Tailwind CSS v4 with the @tailwindcss/postcss plugin, plus tailwind-merge and class-variance-authority for class composition, clsx for conditional classes, lucide-react for icons and date-fns for dates. Server state is handled by @tanstack/react-query at 5.101.0, which is the right choice for an application that polls a remote API and needs caching, request deduplication and background refresh without inventing its own layer. The build scripts are minimal and Next.js native: dev runs next dev with the turbopack flag on port 4000, build runs next build, start runs next start, and lint runs eslint. The dev script hard codes the port, which matches the README's instruction to open localhost:4000. The repository also carries a .env.example with the same variable names, next.config.ts, postcss.config.mjs, an eslint flat config, a TypeScript configuration with TypeScript 5.9.3, and a public directory for static assets. ## Where this inbox is the wrong tool Three cases point elsewhere. The first is an application that must talk to the Cloud API without a third party in the path. The dependency on a hosted Kapso service is fine for a demo, a reference implementation or a team that already uses Kapso, and it is a problem for a regulated deployment, a reseller, or anyone whose data processing agreement does not permit a message broker to sit in the middle. The code is small enough to fork, since the SDK is one dependency, but that is work the adopter inherits. The second is a high volume operation. Real-time updates are auto-polling, which is simple and works, and it is not how you would build a large deployment, where webhooks and a queue are the usual answer. The README does not describe webhook handling, a message store or retry behaviour, so those are things you would add. The third is a use case that is not a conversation. This is a human inbox for a WhatsApp business number. Bulk notifications, campaign sends and automated flows belong to the API and to a scheduler, and this project is a screen for people. There is also a licensing point worth reading carefully. The code is MIT, which is permissive, but the WhatsApp Business Platform itself has its own terms, and the application is a front end to a service that Meta governs. The MIT licence covers this repository, not the platform, and the two should not be confused. ## Conclusion Adopt whatsapp-cloud-inbox if you need a working WhatsApp Cloud API inbox quickly, either as a starting point for an internal agent console or as a reference for how templates, interactive messages and the 24 hour window are supposed to behave from a user interface. Do not adopt it as-is for a production customer facing agent tool without reviewing the Kapso dependency, since the app talks to a Kapso hosted API rather than to Meta directly, and because the project has no GitHub releases and a version of 0.1.0. Verify three things first: which number identifiers your setup already has, since the app discovers PHONE_NUMBER_ID and WABA_ID from Kapso using your API key and can fall back to a single number from the environment; what happens when the 24 hour window has closed, because the app switches to template only mode and will not send free text; and whether the polling model is acceptable, since the README describes real-time updates as auto-polling rather than a webhook. The licence is MIT, the last push was on 2026-10-13, and the repository publishes no GitHub releases. ## FAQ ### What is whatsapp-cloud-inbox? It is an open source inbox for the official WhatsApp Cloud API, built with Next.js in a WhatsApp Web style. It supports text, media, template messages and interactive button messages, and enforces WhatsApp's 24 hour messaging window automatically. ### Does whatsapp-cloud-inbox call the WhatsApp API directly? Not directly. It uses the @kapso/whatsapp-cloud-api package and requires a Kapso API key obtained from app.kapso.ai, and the setup involves connecting a WhatsApp number there first. Environment variables allow a custom endpoint and a base URL on a different host, plus a single-number fallback. ### How do I run whatsapp-cloud-inbox locally? Clone the repository, run npm install, create a .env file with KAPSO_API_KEY and the optional WHATSAPP_API_URL, KAPSO_API_BASE_URL, PHONE_NUMBER_ID and WABA_ID values, then run npm run dev and open http://localhost:4000, with the number selection at http://localhost:4000/settings. ### How does the 24 hour window behave in the inbox? Within 24 hours regular messages can be sent freely, outside that window the app switches to template-only mode with clear messaging about the restriction, and where there have been no inbound messages the user is guided towards sending templates. ### Which message types does whatsapp-cloud-inbox support? Text messages, images, videos, audio and documents, template messages with all parameter types, and interactive button messages. Interactive messages take an optional header, a required body and one to three buttons, each with a unique ID and a title of at most 20 characters. ## Sources - [gokapso/whatsapp-cloud-inbox on GitHub](https://github.com/gokapso/whatsapp-cloud-inbox) - [Issues](https://github.com/gokapso/whatsapp-cloud-inbox/issues) - [License: MIT](https://github.com/gokapso/whatsapp-cloud-inbox/blob/main/LICENSE) - [Project website](https://kapso.com/) - [README](https://github.com/gokapso/whatsapp-cloud-inbox/blob/main/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/gokapso-whatsapp-cloud-inbox