Code Examples
Code Examples
Copy-paste ready examples for the most common integration scenarios. Each example is self-contained and production-ready.
Integration Examples
Browse examples across different use cases. Each snippet uses the JavaScript SDK — equivalent code is available in all other SDKs.
01USSD
USSD Application
Create a multi-level USSD menu that handles user navigation, collects input, and returns dynamic responses.
import { FlowApp } from '@flowapp/sdk'
const client = new FlowApp({ apiKey: process.env.FLOWAPP_API_KEY })
// Create a multi-level USSD flow
const flow = await client.flows.create({
name: 'Customer Support Menu',
channel: 'ussd',
nodes: [
{
id: 'root',
type: 'menu',
content: 'Welcome to Acme\n1. Check Balance\n2. Buy Airtime\n3. Help',
options: [
{ input: '1', next: 'balance' },
{ input: '2', next: 'airtime' },
{ input: '3', next: 'help' },
],
},
{
id: 'balance',
type: 'message',
content: 'Your balance is GHS 45.20',
},
],
})
await client.flows.publish(flow.id)
console.log('Flow live at:', flow.shortcode)02Messaging
Chatbot Integration
Build a chatbot flow that processes natural language messages and routes users through conversation branches.
import { FlowApp } from '@flowapp/sdk'
const client = new FlowApp({ apiKey: process.env.FLOWAPP_API_KEY })
// Handle an incoming message from a chat channel
async function handleMessage(userId: string, text: string) {
// Find or resume an active session for this user
let session = await client.sessions.findActive({ userId, channel: 'whatsapp' })
if (!session) {
session = await client.sessions.create({
flowId: 'flow_chatbot_01',
userId,
channel: 'whatsapp',
})
}
// Submit the user's message and get the next node response
const result = await client.sessions.respond(session.id, { input: text })
return result.response // text to send back to the user
}03Payments
Payment Processing
Initiate a mobile money payment inside a flow session and handle the confirmation callback.
import { FlowApp } from '@flowapp/sdk'
const client = new FlowApp({ apiKey: process.env.FLOWAPP_API_KEY })
// Initiate a mobile money payment inside a flow node
const payment = await client.payments.create({
sessionId: 'ses_01J9...',
amount: 10.00,
currency: 'GHS',
provider: 'mtn_momo',
phone: '+233241234567',
description: 'Airtime purchase',
})
console.log(payment.status) // 'pending'
console.log(payment.reference) // 'TXN_8f3a...'
// FlowApp will fire a payment.completed or payment.failed webhook
// when the provider confirms the transaction04Webhooks
Webhook Handler
A complete Express.js handler that verifies webhook signatures and processes flow events.
import express from 'express'
import crypto from 'crypto'
const app = express()
app.use(express.raw({ type: 'application/json' }))
const WEBHOOK_SECRET = process.env.FLOWAPP_WEBHOOK_SECRET!
app.post('/webhooks/flowapp', (req, res) => {
// 1. Verify the signature
const sig = req.headers['x-flowapp-signature'] as string
const expected = crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(req.body)
.digest('hex')
if (sig !== `sha256=${expected}`) {
return res.status(401).send('Invalid signature')
}
// 2. Parse and handle the event
const event = JSON.parse(req.body.toString())
switch (event.type) {
case 'session.completed':
console.log('Session ended:', event.payload.session_id)
break
case 'payment.completed':
console.log('Payment confirmed:', event.payload.reference)
break
}
res.json({ received: true })
})