Agent USSD Guide

Agent USSD gives field and outlet teams a dedicated channel for operational tasks. Agent flows are intentionally separate from customer USSD so outlet actions stay on *234# while customer self-service stays on *123#.

Note: Customer self-service uses *123#. Agent operations use *234#. Organization quick operations use *321#.

At a glance

Item	Value
Dial code	*234#
Audience	Agents and super agents
Languages	English and siSwati
Session identity	Agent MSISDN
Authentication	Agent PIN before the menu opens
Session timeout	5 minutes of inactivity
Test gateway	https://api.test.emali2.damplabs.com/api/v1/ussd/sessions
Local gateway	http://localhost:8805/ussd_gateway/api/v1/ussd/sessions

Agent menu

Option	Action	What it is for
1	Cash In Service	Start a customer deposit at the outlet
2	Transfer Float	Transfer float to another agent where enabled
3	Withdraw Float	Withdraw operational float where enabled
4	Check Float	Review current float position
5	Commission Report	Check earnings and commission windows
6	My Profile	Review profile details and settings
7	Help & Guidelines	View operating limits and support contacts
0	Logout	Close the agent session

Live menu examples

English PIN gate and menu

Enter your agent PIN to continue.

0. Back

AGENT SERVICES
Agent: John Dlamini (000001)
Type: PREMIUM Agent

1. Cash In Service
2. Transfer Float
3. Withdraw Float
4. Check Float
5. Commission Report
6. My Profile
7. Help & Guidelines
0. Logout

siSwati PIN gate and menu

Faka i-agent PIN yakho kuze uchubeke.

0. Buyela emuva

AGENT SERVICES
Agent: John Dlamini (000001)
Luhlobo: PREMIUM Agent

1. Faka Imali
2. Dlulisela Float
3. Khupha Float
4. Hlola Float
5. Commission Report
6. Iphrofayela Yami
7. Lusito
0. Phuma

Session lifecycle

1. Agent dials *234#.
2. The session starts with language selection.
3. After language selection, the gateway shows the agent PIN challenge immediately.
4. Once the agent PIN is accepted, the session stays in the selected language and the agent menu opens.
5. The agent can navigate to float, profile, help, and cash-in flows until logout or timeout.

Simulator request format

{
  "sessionId": "agent-menu-001",
  "msisdn": "+26876543001",
  "text": "",
  "serviceCode": "*234#",
  "networkCode": "ALL",
  "newSession": true
}

If your gateway environment enforces request signing, include the X-Emali2-Ussd-Key header in the simulator request. Public test and local flows may not require it.

Flow examples

1. Start an agent session and authenticate

BASE_URL="https://api.test.emali2.damplabs.com/api/v1/ussd/sessions"
SESSION_ID="agent-menu-001"

curl -sS "$BASE_URL" \
  -H 'Content-Type: application/json' \
  -d '{
    "sessionId":"'"$SESSION_ID"'",
    "msisdn":"+26876543001",
    "text":"",
    "serviceCode":"*234#",
    "networkCode":"ALL",
    "newSession":true
  }'

curl -sS "$BASE_URL" \
  -H 'Content-Type: application/json' \
  -d '{
    "sessionId":"'"$SESSION_ID"'",
    "msisdn":"+26876543001",
    "text":"1",
    "serviceCode":"*234#",
    "networkCode":"ALL",
    "newSession":false
  }'

curl -sS "$BASE_URL" \
  -H 'Content-Type: application/json' \
  -d '{
    "sessionId":"'"$SESSION_ID"'",
    "msisdn":"+26876543001",
    "text":"1234",
    "serviceCode":"*234#",
    "networkCode":"ALL",
    "newSession":false
  }'

2. Open the help screen

The help screen gives quick operating guidance for outlet teams.

curl -sS "$BASE_URL" \
  -H 'Content-Type: application/json' \
  -d '{
    "sessionId":"'"$SESSION_ID"'",
    "msisdn":"+26876543001",
    "text":"7",
    "serviceCode":"*234#",
    "networkCode":"ALL",
    "newSession":false
  }'

Typical response:

AGENT GUIDELINES
Cash In/Out Limits:
Min: E10, Max: E5000

Working Hours:
6:00 AM - 10:00 PM

Emergency Support:
Call: 2505 0000

3. Start a cash-in flow

curl -sS "$BASE_URL" \
  -H 'Content-Type: application/json' \
  -d '{
    "sessionId":"'"$SESSION_ID"'",
    "msisdn":"+26876543001",
    "text":"1",
    "serviceCode":"*234#",
    "networkCode":"ALL",
    "newSession":false
  }'

Typical response:

Cash In Service
Help customer deposit money to their wallet.
Enter customer's mobile number:

4. Check float

curl -sS "$BASE_URL" \
  -H 'Content-Type: application/json' \
  -d '{
    "sessionId":"'"$SESSION_ID"'",
    "msisdn":"+26876543001",
    "text":"4",
    "serviceCode":"*234#",
    "networkCode":"ALL",
    "newSession":false
  }'

Typical response:

Float Balance
Checking your current float...
Please wait.

Operating guidance

Cash-in

• Start from 1. Cash In Service.
• Enter the customer MSISDN.
• Continue through the amount and confirmation prompts shown by the menu.
• Give the customer the completion confirmation before the customer leaves the outlet.

Float operations

• Use 2. Transfer Float or 3. Withdraw Float only if the agent role and backend configuration allow it.
• Use 4. Check Float before large outlet operations.
• Supervisors should still use the web channel for reconciliation and end-of-day review.

Commissions and profile

• Use 5. Commission Report for earnings windows.
• Use 6. My Profile for profile details, PIN-related actions, and support-linked options.

Customer cash-out handoff

Customer cash-out does not start from the agent dial code.

1. The customer initiates cash out on *123#.
2. The customer enters the agent till and amount.
3. The customer receives a withdrawal code after confirmation.
4. The agent verifies the handoff at the outlet and completes the cash movement.

This separation keeps customer-authorized withdrawals on the customer channel and avoids mixing them into the agent root menu.

Rollout note

The root menu, language selection, PIN gate, and help entry are live and verified. Transactional agent submenu enablement can still vary by role, environment, and service-provider rollout policy, so supervisor sign-off is recommended before field training material is distributed.

Security model

Important: After language selection, the agent must enter a valid agent PIN before the root menu is shown.

• Agent operations are bound to the agent MSISDN and the live session.
• The dedicated dial code prevents customer menus and agent menus from overlapping.
• Logout is available directly from the agent root menu.

Error handling and troubleshooting

Symptom	What it usually means	What the agent should do
Incorrect PIN	Wrong agent PIN	Retry carefully or use the supported PIN-reset path
Agent not found	The MSISDN is not mapped to an active agent	Confirm onboarding and MSISDN mapping
Float operation not available	The role or backend permissions are limited	Use web back office or supervisor workflow
Session restarted	The session timed out	Dial again and restart the action

Related guides

• Customer USSD Guide
• Agent Guide
• Channels Matrix