> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kairosafrika.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Response Format

> Learn how to structure responses from your webhook endpoint to Kairos Afrika

# 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:

| Field         | Type   | Required | Description                         | Example                 |
| ------------- | ------ | -------- | ----------------------------------- | ----------------------- |
| `sessionId`   | string | Yes      | Same session ID from the request    | `"171632898024603649"`  |
| `ussdString`  | string | Yes      | Message to display to the user      | `"): Code not active."` |
| `msisdn`      | string | Yes      | Same phone number from the request  | `"233559400612"`        |
| `timestamp`   | string | Yes      | Current timestamp                   | `"171632898024603649"`  |
| `messageType` | string | Yes      | Response message type (usually "0") | `"0"`                   |

## Example Response

Based on the request example, here's how your endpoint should respond:

```json theme={null}
{
    "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

### Menu Response

```json theme={null}
{
    "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

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

### Error Response

```json theme={null}
{
    "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

<Note>
  Remember that `https://example.com/ussd` is just an example URL. Replace it with your actual webhook endpoint when integrating with Kairos Afrika.
</Note>