---
name: whatsapp-grocery-delivery-nodejs
title: "WhatsApp AI Grocery Delivery Assistant"
description: "AI-powered grocery delivery assistant on WhatsApp — 12 tools, voice ordering, real-time dashboard"
language: nodejs
framework: express
telnyx_products: [WhatsApp Business API, AI Inference, Number Lookup, Audio Transcription]
---
# WhatsApp AI Grocery Delivery Assistant
AI-powered grocery delivery assistant on WhatsApp — 12 AI tools, voice note ordering, real-time operator dashboard.
## Why Telnyx
Telnyx is an **AI Communications Infrastructure** platform — voice, messaging, SIP, AI, and IoT on one private, global network. This example combines four Telnyx APIs behind a single API key: WhatsApp Business messaging delivers rich interactive messages, AI Inference powers the tool-calling agent, Number Lookup validates customer phone numbers, and Audio Transcription converts voice notes into grocery orders. The result is a full-featured delivery assistant that runs on one platform with no third-party AI or messaging vendors.
## Telnyx API Endpoints Used
- **WhatsApp Messaging**: `POST /v2/messages/whatsapp` — [API reference](https://developers.telnyx.com/api/v2/whatsapp)
- **AI Inference**: `POST /v2/ai/chat/completions` — [API reference](https://developers.telnyx.com/api/inference/chat-completions)
- **Number Lookup**: `GET /v2/number_lookup/{phone_number}` — [API reference](https://developers.telnyx.com/api/number-lookup/number-lookup)
- **Audio Transcription**: `POST /v2/ai/audio/transcriptions` — [API reference](https://developers.telnyx.com/api/inference/audio-transcriptions)
## Architecture
```
WhatsApp User
|
v
Telnyx WhatsApp API
|
v
POST /webhooks/whatsapp
|
v
+------------------+
| Message Router | -- text, interactive, audio
+--------+---------+
|
+-----+------+
| |
text/ audio
interactive |
| v
| Telnyx Audio
| Transcription API
| |
+-----+-----+
|
v
+------------------+
| AI Inference | -- tool-calling loop (up to 10 turns)
| 12 tools: |
| browse_products |
| add_to_cart |
| view_cart |
| update_cart |
| get_delivery_ |
| slots |
| place_order |
| track_delivery |
| reschedule_ |
| delivery |
| handle_ |
| substitution |
| reorder |
| register_ |
| customer |
| send_whatsapp |
+--------+---------+
|
+-----+------+
| |
tool calls send_whatsapp
| |
v v
SQLite DB Telnyx WhatsApp API
(orders, |
cart, v
products) Customer
|
v
SSE /stream --> Operator Dashboard
```
## Environment Variables
Copy `.env.example` to `.env` and fill in:
| Variable | Type | Example | Required | Description | Where to get it |
|----------|------|---------|----------|-------------|-----------------|
| `TELNYX_API_KEY` | `string` | `KEYyour-main-api-key-here` | **yes** | Telnyx API v2 key (AI Inference, Number Lookup) | [Portal](https://portal.telnyx.com/api-keys) · [CLI: `telnyx auth`](https://developers.telnyx.com/development/cli) |
| `TELNYX_WHATSAPP_API_KEY` | `string` | `KEYyour-whatsapp-api-key-here` | **yes** | Telnyx API key with WhatsApp Business Account access | [Portal](https://portal.telnyx.com/api-keys) |
| `WHATSAPP_NUMBER` | `string` | `+1XXXXXXXXXX` | **yes** | Your WhatsApp Business number in E.164 format | [Portal](https://portal.telnyx.com) → WhatsApp |
| `WHATSAPP_MESSAGING_PROFILE_ID` | `string` | `your-messaging-profile-id-here` | **yes** | Messaging profile ID linked to your WABA | [Portal](https://portal.telnyx.com) → Messaging |
| `AI_MODEL` | `string` | `zai-org/GLM-5.3-Flash` | no | Telnyx AI Inference model name | [Models](https://developers.telnyx.com/docs/inference/models) |
| `PORT` | `integer` | `3000` | no | HTTP server port | - |
> **Agent / CLI access** — provision resources programmatically with the [Telnyx CLI](https://developers.telnyx.com/development/cli):
>
> ```bash
> telnyx auth login
> telnyx available-phone-numbers list --country US --features sms
> telnyx number-orders create --phone-number +15551234567
> telnyx messaging-profiles create --name "FreshCart WhatsApp"
> ```
>
> Full API discovery: [llms-full.txt](https://developers.telnyx.com/llms-full.txt) · [CLI docs](https://developers.telnyx.com/development/cli)
## Setup
```bash
git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/whatsapp-grocery-delivery-nodejs
cp .env.example .env # <- fill in your credentials
npm install
node server.js # starts on http://localhost:3000
```
Programmatic / CLI setup
```bash
# Install CLI — https://developers.telnyx.com/development/cli
go install github.com/team-telnyx/telnyx-cli/cmd/telnyx@latest
telnyx auth login
# Provision resources
telnyx available-phone-numbers list --country US --features sms
telnyx number-orders create --phone-number +15551234567
telnyx messaging-profiles create --name "FreshCart WhatsApp"
```
For full API discovery, point your agent at [`llms-full.txt`](https://developers.telnyx.com/llms-full.txt).
### Webhook Configuration
1. Expose your local server:
```bash
ngrok http 3000
```
2. Copy the HTTPS URL and configure in [Telnyx Portal](https://portal.telnyx.com):
- **Messaging Profile** → Webhook URL → `https://.ngrok.io/webhooks/whatsapp`
## API Reference
The full typed reference lives in [API.md](https://raw.githubusercontent.com/team-telnyx/telnyx-code-examples/main/whatsapp-grocery-delivery-nodejs/API.md). Summary:
| Method | Path | Purpose |
|--------|------|---------|
| `POST` | `/webhooks/whatsapp` | Inbound WhatsApp webhook |
| `GET` | `/health` | Health check |
| `GET` | `/api/config` | Dashboard config |
| `GET` | `/api/categories` | Product categories |
| `GET` | `/api/products` | Product search |
| `GET` | `/api/orders` | List orders |
| `GET` | `/api/orders/:id` | Single order |
| `POST` | `/api/orders/:id/advance` | Advance order status |
| `GET` | `/api/substitutions` | List substitutions |
| `GET` | `/api/delivery-slots` | Delivery slots |
| `GET` | `/api/cart/:phone` | Cart for customer |
| `GET` | `/api/ui-events` | UI events |
| `POST` | `/api/customers` | Register customer |
| `GET` | `/api/customers/:phone` | Get customer |
| `GET` | `/api/conversations` | Conversation history |
| `DELETE` | `/api/conversations` | Clear conversations |
| `GET` | `/stream` | SSE event stream |
## Troubleshooting
| Issue | Cause | Fix |
|-------|-------|-----|
| `401 Unauthorized` on WhatsApp send | Invalid or missing API key | Verify `TELNYX_WHATSAPP_API_KEY` in `.env` matches your WABA-enabled key in the [Portal](https://portal.telnyx.com/api-keys) |
| Webhook not received | Local server not publicly reachable | Expose with ngrok (`ngrok http 3000`) and set the webhook URL on your Messaging Profile |
| AI response slow or times out | Large conversation history or model load | The first request may be slower; subsequent requests are faster. Check `AI_MODEL` is valid |
| Two API keys required | WhatsApp needs WABA-enabled key; Inference uses main key | Set both `TELNYX_API_KEY` (main) and `TELNYX_WHATSAPP_API_KEY` (WABA) in `.env` |
| Voice note not transcribed | Audio URL from untrusted domain | Only Telnyx-hosted media URLs are accepted (SSRF prevention) |
| Wrong API key at runtime | Shell env overrides `.env` values | The app manually parses `.env` with override — verify with startup log showing first 12 chars of each key |
## Agent Discovery
This example is part of the [Telnyx Code Examples](https://github.com/team-telnyx/telnyx-code-examples) catalog.
- **Agent signup**: [telnyx.com/agent-signup.md](https://telnyx.com/agent-signup.md) — automated account provisioning via agent mail; get an API key with no human intervention
- **Agent CLI**: [github.com/team-telnyx/ai/tree/main/cli](https://github.com/team-telnyx/ai/tree/main/cli) — composite commands for agents ([commands reference](https://github.com/team-telnyx/ai/tree/main/cli/src/commands))
- **Agent skills**: [github.com/team-telnyx/ai/tree/main/skills](https://github.com/team-telnyx/ai/tree/main/skills)
- **Telnyx AI repo**: [github.com/team-telnyx/ai](https://github.com/team-telnyx/ai)
- **LLM-optimized docs**: [`llms-full.txt`](https://developers.telnyx.com/llms-full.txt)
- **Example index**: [`llms.txt`](https://raw.githubusercontent.com/team-telnyx/telnyx-code-examples/main/llms.txt)
- **Telnyx CLI (human)**: [developers.telnyx.com/development/cli](https://developers.telnyx.com/development/cli) — `go install github.com/team-telnyx/telnyx-cli/cmd/telnyx@latest`
## Related Examples
- [WhatsApp Restaurant Reservation (Node.js)](https://raw.githubusercontent.com/team-telnyx/telnyx-code-examples/main/whatsapp-restaurant-reservation-nodejs/README.md)
- [WhatsApp Order Tracking Notifications (Python)](https://raw.githubusercontent.com/team-telnyx/telnyx-code-examples/main/whatsapp-order-tracking-notifications-python/README.md)
- [WhatsApp SMS Bridge (Python)](https://raw.githubusercontent.com/team-telnyx/telnyx-code-examples/main/whatsapp-sms-bridge-python/README.md)
- [AI Assistant Multi Tool (Python)](https://raw.githubusercontent.com/team-telnyx/telnyx-code-examples/main/ai-assistant-multi-tool-python/README.md)
- [Two-Way SMS Chat (Node.js)](https://raw.githubusercontent.com/team-telnyx/telnyx-code-examples/main/two-way-sms-chat-nodejs/README.md)
## Resources
- [WhatsApp Business API Guide](https://developers.telnyx.com/docs/messaging/whatsapp)
- [AI Inference Guide](https://developers.telnyx.com/docs/inference)
- [Number Lookup API Reference](https://developers.telnyx.com/api/number-lookup/number-lookup)
- [Audio Transcription API Reference](https://developers.telnyx.com/api/inference/audio-transcriptions)
- [Node.js SDK](https://developers.telnyx.com/development/sdk/node)
- [WhatsApp Business Product Page](https://telnyx.com/products/whatsapp-api)
- [SMS API Product Page](https://telnyx.com/products/sms-api)
- [AI Inference Pricing](https://telnyx.com/pricing/inference)
- [Telnyx Developer Docs](https://developers.telnyx.com)
- [Telnyx Portal](https://portal.telnyx.com)