Firebase Extension
For developers building mobile apps, web applications, and serverless backends on Google Firebase, WhatsBox maintains an official open-source Firebase Extension: firestore-send-whatsapp-message.
Whenever your backend or client application writes a document into a designated Cloud Firestore collection, the extension listens for the write event and automatically dispatches a WhatsApp template message via the WhatsBox API.
WhatsBox Firebase Firestore Extension
View the open-source extension source code, installation guides, and release notes on GitHub at whatsb/firebase-extension-firestore-send-whatsapp-message.
Architecture Overview
- Your application creates a new document in your specified Firestore collection (e.g.,
whatsapp_messages). - A serverless Cloud Function managed by Firebase Extension triggers on document creation.
- The extension extracts the recipient, template name, and dynamic parameters, then calls the WhatsBox REST API.
- The extension updates the original Firestore document with delivery metadata, including the WhatsBox message ID, delivery state, and error logs if any.
Installation & Configuration
Install the Extension
Install the extension directly using the Firebase CLI or through the Firebase Console:
firebase ext:install whatsb/firestore-send-whatsapp-message --project=YOUR_PROJECT_ID
Configure Parameters
During installation, specify your project credentials:
WHATSBOX_API_KEY: Your secret API key from WhatsBox (Settings > API Keys).WHATSAPP_CHANNEL_ID: Your connected WhatsApp sender channel ID.COLLECTION_PATH: The Firestore collection path to monitor (e.g.,whatsapp_outboxormessages).
Write Documents to Firestore
To trigger a WhatsApp message, simply add a document to the monitored Firestore collection:
import { getFirestore, collection, addDoc } from 'firebase/firestore'
const db = getFirestore()
await addDoc(collection(db, 'whatsapp_outbox'), {
to: '+16317471111',
template: {
name: 'order_confirmation',
language: 'en',
components: [
{
type: 'body',
parameters: [
{ type: 'text', text: 'Alex' },
{ type: 'text', text: 'ORD-9842' }
]
}
]
}
})
Monitor Document Lifecycle
Once processed, the extension automatically mutates the Firestore document with result fields:
delivery_status: Set toPENDING,SUCCESS, orERROR.whatsbox_message_id: The unique tracking ID assigned by WhatsBox.processed_at: Firestore server timestamp when the message was sent.error: Diagnostic error message if validation or dispatch failed.