whatsapp-broadcasts-example - GitLite

KO | EN

gitlite — search

#machine-learning #hacktoberfest #kubernetes #data-science #shell #open-source #containers #http #awesome-list #developer-tools

whatsapp-broadcasts-example

(★ 49)

Example Next.js app demonstrating Kapso's Broadcasts API for WhatsApp mass messaging campaigns.

File Explorer

ZIP Download

- settings.local.json
- file.svg
- globe.svg
- next.svg
- vercel.svg
- window.svg
- - favicon.ico
  - globals.css
  - layout.tsx
  - page.tsx
- - csv-parser.ts
  - kapso-api.ts
  - utils.ts
- - index.ts
.gitignore
components.json
eslint.config.mjs
LICENSE
next.config.ts
package-lock.json
package.json
postcss.config.mjs
README.md
tsconfig.json

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

Command Glossary

Commands referenced in this DOCs, explained below.

🔍

`git clone`

View Details ▼

Clone an existing repository.

git clone {{remote_repository_location}} {{path/to/directory}}

Clone an existing repository into a new directory (the default directory is the repository name):

git clone --recursive {{remote_repository_location}}

Clone an existing repository and its submodules:

git clone {{[-n|--no-checkout]}} {{remote_repository_location}}

Clone only the `.git` directory of an existing repository:

🔍

`npm install`

View Details ▼

Install Node packages.

npm {{[i|install]}}

Install dependencies listed in `package.json`:

npm {{[i|install]}} {{package_name}}@{{version}}

Download a specific version of a package and add it to the list of dependencies in `package.json`:

npm {{[i|install]}} {{package_name}} {{[-D|--save-dev]}}

Download the latest version of a package and add it to the list of dev dependencies in `package.json`:

🔍

`npm run`

View Details ▼

Run a script.

npm run

List available scripts:

npm run {{script_name}}

Run a script:

npm run {{script_name}} -- {{argument}} {{--option}}

Pass arguments to a script:

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Example Next.js app demonstrating Kapso's Broadcasts API for WhatsApp mass messaging campaigns.

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fgokapso%2Fwhatsapp-broadcasts-example&env=KAPSO_API_KEY,PHONE_NUMBER_ID,NEXT_PUBLIC_PHONE_NUMBER_ID,BUSINESS_ACCOUNT_ID&envDescription=Required%20Kapso%20credentials&envLink=https%3A%2F%2Fdocs.kapso.ai)

## Features

- **5-step wizard UI** - Clean, intuitive stepper interface
- **Batch recipient upload** - Add up to 1,000 recipients per request via CSV
- **Real-time progress tracking** - Auto-polling during broadcast send
- **Recipient-level analytics** - Per-phone delivery status with pagination
- **Response rate metrics** - Track engagement and campaign performance

## Quick start

```bash
# Clone the repository
git clone https://github.com/gokapso/whatsapp-broadcasts-example.git
cd whatsapp-broadcasts-example

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Add your Kapso API key and WhatsApp phone number ID

# Run development server
npm run dev
```

Open [http://localhost:4000](http://localhost:4000)

## Setup

### 1. Get Kapso API key

1. Sign up at [app.kapso.ai](https://app.kapso.ai)
2. Go to Sidebar → API Keys
3. Create a new API key
4. Copy the key to your `.env` file

### 2. Connect WhatsApp

1. In your Kapso dashboard, go to Connected numbers and connect a WhatsApp Business account
2. Copy the phone number ID from your connected WhatsApp number
3. Copy your WhatsApp Business Account ID
4. Add both IDs to your `.env` file:
   - `PHONE_NUMBER_ID` - Used for sending broadcasts
   - `NEXT_PUBLIC_PHONE_NUMBER_ID` - Used for client-side display
   - `BUSINESS_ACCOUNT_ID` - Used for fetching templates

### 3. Create templates

1. In Kapso dashboard (or directly in Meta), create WhatsApp message templates
2. Get them approved by Meta
3. Templates will appear in the app automatically

## CSV format

Upload a CSV file with phone numbers and template parameters:

```csv
phone,param1,param2
+15551234567,John,Order123
+15559876543,Jane,Order456
```

- **First column**: Phone number (E.164 format with + prefix)
- **Remaining columns**: Template parameters in order

## API endpoints

This app uses the following Kapso API endpoints:

- `GET /whatsapp_templates` - Fetch approved templates
- `POST /whatsapp_broadcasts` - Create draft broadcast
- `POST /whatsapp_broadcasts/:id/recipients` - Add recipients
- `POST /whatsapp_broadcasts/:id/send` - Send broadcast
- `GET /whatsapp_broadcasts/:id` - Get broadcast status
- `GET /whatsapp_broadcasts/:id/recipients` - List recipients

## Tech stack

- **Next.js 15** - React framework
- **TypeScript** - Type safety
- **Tailwind CSS v4** - Styling
- **shadcn/ui** - UI components
- **Kapso API** - WhatsApp broadcasts

## Project structure

```
src/
├── app/
│   ├── api/
│   │   ├── broadcasts/          # Broadcast API routes
│   │   └── templates/           # Template API routes
│   └── page.tsx                 # Main stepper UI
├── components/ui/               # shadcn components
├── lib/
│   ├── kapso-api.ts            # Kapso API client
│   ├── csv-parser.ts           # CSV parsing utilities
│   └── utils.ts                # Utility functions
└── types/index.ts              # TypeScript types
```

## Documentation

- [Create Broadcast API](https://docs.kapso.ai/api-reference/whatsapp-broadcasts/create-broadcast)
- [List WhatsApp Templates API](https://docs.kapso.ai/api-reference/whatsapp-templates/list-whatsapp-templates)
- [Full API Reference](https://docs.kapso.ai/api-reference)

## License

MIT