Knox Service Plugin managed config: configure call and messaging block/allowlist rules

Android

This article explains how to configure call and messaging restrictions on Samsung devices using Knox Service Plugin (KSP) managed configuration in Esper. If you're attempting to set per-device call blocking or messaging policies and encountering errors or null values, follow these steps to ensure your configuration uses the correct schema.

Before you begin

Verify that the following prerequisites are met on your target device:

• Knox Service Plugin app (com.samsung.android.knox.kpu) is installed and active
• Your Knox premium license key is active and resolving on-device (you can confirm this in the KSP Troubleshooter)
• Basic KSP managed configuration fields such as profileName and kpePremiumLicenseKey are already working

Understand the schema limitation

The Knox Service Plugin managed configuration schema — including all valid field names for call and messaging controls — is defined and maintained exclusively by Samsung Knox, not by Esper. Esper delivers your managed configuration JSON to the KSP app but does not validate or document the schema itself. If you see error 12003 ("unrecognized field") or messagingPolicy: null in the KSP Troubleshooter, the issue is typically incorrect field names in your JSON payload.

Step 1: Obtain the correct schema from Samsung

The field names for call and messaging policies vary by KSP version and device firmware. You must source the authoritative schema directly from Samsung:

1. Visit the Samsung Knox Developer Portal at https://knox.samsung.com/
2. Log in with your Knox account credentials
3. Locate the OEMConfig or managed configuration XML/JSON schema documentation for KSP
4. Find the call and messaging policy subtree, specifically fields for:
   • Blocking all inbound calls
   • Blocking all outbound calls
   • Defining an E.164 number allowlist (for example, +12025550100)
5. Document the exact field names provided by Samsung — these are the keys you will use in your JSON payload

If you cannot locate this documentation, contact Samsung Knox Support directly through the Knox Developer Portal.

Step 2: Construct your managed configuration JSON

Once you have the correct field names from Samsung, build your JSON payload following this structure (replace placeholder keys with Samsung-validated field names):

{
 "kind": "androidenterprise#managedConfiguration",
 "productId": "app:com.samsung.android.knox.kpu",
 "managedProperty": [
 {
 "key": "profileName",
 "valueString": "CallPolicy-Device-001"
 },
 {
 "key": "kpePremiumLicenseKey",
 "valueString": "${esper.knoxKey}"
 },
 {
 "key": "<samsung_validated_call_restriction_key>",
 "valueBundle": {
 "<block_all_incoming_key>": true,
 "<block_all_outgoing_key>": true,
 "<allowlist_key>": ["+12025550100"]
 }
 }
 ]
}

Important: Do not use this payload verbatim. Every placeholder (angle brackets) must be replaced with the exact field names provided by Samsung for your KSP version.

Step 3: Deploy the per-device configuration via Esper

You can deliver your validated JSON to individual devices while keeping them on the same Blueprint. This approach supports unique per-device allowlists or policies.

Option 1: Via the Esper Console

1. Navigate to Devices & Groups → [Device Name] → Apps
2. Find and select Knox Service Plugin in the app list
3. Click Managed Config
4. Paste your validated JSON into the textarea
5. Save and apply

Option 2: Via the Esper API

1. Use the endpoint PATCH /v0/enterprise/{enterprise_id}/devices/{device_id}/
2. In the request body, target UPDATE_DEVICE_CONFIG with the managedAppConfigurations["com.samsung.android.knox.kpu"] parameter
3. Include your validated JSON payload
4. Submit the request

Each device can have its own unique JSON payload without affecting your Blueprint, making this approach scalable for thousands of devices with individual allowlists.

Step 4: Verify the configuration

After deployment, confirm that your policy is active and working:

1. On the device, open the KSP Troubleshooter (available in the KSP app interface or system settings)
2. Check that the call policy node (or equivalent) shows the expected values — it should not display null
3. If you configured an allowlist:
   • Attempt a call from a number not on the allowlist — it should be blocked
   • Attempt a call from an allowlisted number — it should connect normally
4. If you configured blocking all calls, verify that all inbound and outbound calls are blocked

Troubleshoot persistent errors

If you still see error 12003 or null values:

• Double-check that all field names in your JSON exactly match Samsung's documentation — even minor capitalization or spelling differences will cause errors
• Confirm the KSP version installed on the device and verify that the schema you obtained from Samsung matches that version
• Check device firmware version; some call/messaging policy fields may only be available on certain firmware versions
• Open the KSP Troubleshooter and capture the full output showing which fields are null or erroring

If the issue persists after validating your schema:

• Gather the exact JSON payload you sent, the device model, firmware version, KSP version, and the complete KSP Troubleshooter output
• Contact Esper Support with this information so we can investigate whether there is a delivery issue on the Esper side

Still need help?

If you've followed these steps and your call and messaging restrictions are still not working, contact Esper Support. include your JSON payload, device details, KSP version, firmware version, and KSP Troubleshooter output so we can assist you quickly.