Skip to main content

​
Webhook Response Format

Your webhook endpoint must return a properly formatted JSON response that tells Kairos Afrika what to display to the user and how to handle the USSD session.

​
Response Details

  • Status Code: 200 OK
  • Content-Type: application/json
  • Response Time: Should respond within 10 seconds

​
Response Body Structure

Your response should contain the following fields:
FieldTypeRequiredDescriptionExample
sessionIdstringYesSame session ID from the request"171632898024603649"
ussdStringstringYesMessage to display to the user"): Code not active."
msisdnstringYesSame phone number from the request"233559400612"
timestampstringYesCurrent timestamp"171632898024603649"
messageTypestringYesResponse message type (usually “0”)"0"

​
Example Response

Based on the request example, here’s how your endpoint should respond: 
{
    "sessionId": "171632898024603649",
    "ussdString": "): Code not active.",
    "msisdn": "233559400612", 
    "timestamp": "171632898024603649",
    "messageType": "0"
}

​
Field Descriptions

​
sessionId

Return the exact same sessionId that was sent in the request. This helps Kairos Afrika track the session.

​
ussdString

The message that will be displayed to the user on their mobile device. This can be:
  • A simple text message
  • A menu with options
  • An error message
  • A confirmation message

​
msisdn

Return the same phone number (msisdn) that was provided in the request.

​
timestamp

Current timestamp. Can be in various formats - Unix timestamp, ISO string, etc.

​
messageType

Usually "0" for standard responses. May vary based on your specific implementation needs.

​
Response Examples

{
    "sessionId": "171632898024603649",
    "ussdString": "Welcome to MyApp\n1. Check Balance\n2. Transfer Money\n3. Help\n0. Exit",
    "msisdn": "233559400612",
    "timestamp": "1716328980246",
    "messageType": "0"
}

​
Balance Check Response

{
    "sessionId": "171632898024603649", 
    "ussdString": "Your current balance is GHS 45.50\n\nThank you for using MyApp!",
    "msisdn": "233559400612",
    "timestamp": "1716328980246", 
    "messageType": "0"
}

​
Error Response

{
    "sessionId": "171632898024603649",
    "ussdString": "Invalid option selected. Please try again.\n\n1. Check Balance\n2. Transfer Money\n0. Exit", 
    "msisdn": "233559400612",
    "timestamp": "1716328980246",
    "messageType": "0"
}

​
Best Practices

​
Message Formatting

  • Keep messages concise and clear
  • Use \n for line breaks in menus
  • Limit message length to avoid truncation on mobile devices
  • Use clear numbering for menu options (1, 2, 3, etc.)

​
Session Management

  • Always return the same sessionId from the request
  • Maintain session state on your end using the sessionId
  • Handle session timeouts gracefully

​
Error Handling

  • Provide clear error messages for invalid inputs
  • Always return a valid JSON response, even for errors
  • Include helpful guidance in error messages

​
Performance

  • Respond quickly (within 10 seconds)
  • Cache frequently accessed data
  • Use efficient database queries

​
Session Flow Example

Here’s how a typical USSD session might flow:
  1. User dials: *889*90#
  2. Your response: Welcome menu
  3. User selects: 1 (Check Balance)
  4. Your response: Balance information
  5. Session ends or continues based on your logic

​
Testing Your Integration

To test your webhook:
  1. Set up a test endpoint that logs incoming requests
  2. Verify you can parse the request JSON correctly
  3. Test different response scenarios (menus, errors, confirmations)
  4. Ensure your responses display correctly on mobile devices
Remember that https://example.com/ussd is just an example URL. Replace it with your actual webhook endpoint when integrating with Kairos Afrika.