Building USSD Applications with Node.js in Nigeria: MTN & Airtel Integration Guide

Why USSD Still Matters in Nigeria in 2025

Despite smartphone penetration growth, over 40% of Nigerian mobile users still rely on USSD (*123#, *737#, etc.) for banking and service access. If your product serves mass-market Nigerian users — especially in rural areas — USSD is not optional.

At Neobot Tech, we've built USSD integrations for fintech, agricultural platforms, and government service portals. Here's the definitive guide.

How USSD Works in Nigeria

USSD (Unstructured Supplementary Service Data) is a protocol used by GSM networks. When a user dials 384001#:

1. MTN/Airtel routes the request to your registered callback URL
2. Your server receives the request and returns a menu (text, max 182 characters per response)
3. User selects an option, request comes back with their input
4. Session continues until you send a final response or session times out (90–180 seconds on MTN)

Getting Started with Africa's Talking

Africa's Talking (africastalking.com) is the simplest way to register a USSD shortcode in Nigeria. They handle the MNO relationships with MTN, Airtel, Glo, and 9Mobile.

Steps:

1. Create an account at africastalking.com
2. Apply for a USSD shortcode (usually 384XXXX# format for sandbox)
3. Set your callback URL (your Node.js server)
4. Fund your AT wallet for live traffic

Building the USSD Handler

// app/api/ussd/route.ts
import { NextRequest, NextResponse } from 'next/server';

interface UssdRequest {
  sessionId: string;
  serviceCode: string;
  phoneNumber: string;
  text: string; // All user inputs concatenated with '*'
}

export async function POST(req: NextRequest) {
  const formData = await req.formData();
  
  const sessionId = formData.get('sessionId') as string;
  const phoneNumber = formData.get('phoneNumber') as string;
  const text = formData.get('text') as string;
  
  const inputs = text.split('*').filter(Boolean);
  const level = inputs.length;
  
  let response = '';
  
  if (level === 0) {
    // Main menu
    response = `CON Welcome to Neobot Tech Services
1. Check Project Status
2. Request a Quote
3. Contact Support
0. Exit`;
  } else if (inputs[0] === '1') {
    if (level === 1) {
      response = 'CON Enter your project code:';
    } else {
      const projectCode = inputs[1];
      const project = await getProjectByCode(projectCode);
      if (project) {
        response = `END Project: ${project.title}
Status: ${project.status}
Progress: ${project.progress}%
PM: ${project.pmName}`;
      } else {
        response = 'END Project code not found. Contact hello@neobottech.org';
      }
    }
  } else if (inputs[0] === '2') {
    response = `END To request a quote, visit:
neobottech.org/estimator
or call: 08122531154
(Mon-Fri, 9am-6pm)`;
  } else if (inputs[0] === '3') {
    response = `END Support contacts:
Email: hello@neobottech.org
WhatsApp: 08122531154
Hours: Mon-Fri 9am-6pm WAT`;
  } else {
    response = 'END Thank you for using Neobot Tech.';
  }
  
  return new NextResponse(response, {
    headers: { 'Content-Type': 'text/plain' },
  });
}

Session Management with Redis

USSD sessions are stateless by default. For multi-step flows (like payment confirmations), use Redis to store session state:

import { redis } from '@/lib/redis';

async function getSessionData(sessionId: string) {
  const data = await redis.get(`ussd:${sessionId}`);
  return data ? JSON.parse(data) : {};
}

async function setSessionData(sessionId: string, data: object) {
  await redis.setex(`ussd:${sessionId}`, 300, JSON.stringify(data)); // 5min TTL
}

Character Limits: Critical for Nigerian USSD

• Per response: Maximum 182 characters (test on both MTN and Airtel, limits vary slightly)
• CON: Means "continue session" — show a menu
• END: Means "terminate session" — show final message

Always test your menus on a real phone before going live.

Conclusion

USSD is a powerful channel for reaching mass-market Nigerian users. Our backend engineering services include USSD system design and Africa's Talking integration — contact us to scope your project.