Unified Messaging API

Unified Messaging API is recommended for new integrations. It chooses channels, fallback behavior, OTP delivery, and logs from one kfmsg_ token.

Endpoint

POST https://karflows.com/api/omni/send

Headers

Authorization: Bearer kfmsg_your_token
Content-Type: application/json

Send text

curl -X POST "https://karflows.com/api/omni/send" \
  -H "Authorization: Bearer kfmsg_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+255700000000",
    "text": "Your order has been received.",
    "channels": ["whatsapp_qr", "whatsapp_meta", "sms"],
    "deliveryMode": "fallback",
    "whatsappFrom": "447405993704",
    "sender": "DM BLUEWAVE"
  }'

Parameters

Parameter	Type	Required	Description
`to`	string	Yes	Recipient phone number with country code
`text`	string	Yes	Message body
`channels`	array	No	Ordered list of `whatsapp_qr`, `whatsapp_meta`, and `sms`
`deliveryMode`	string	No	`fallback` or `all`; uses the account default when omitted
`fallback`	boolean	No	Legacy switch that can limit fallback mode to the first channel
`whatsappFrom`	string	QR only	A connected QR sender; KarFlows auto-selects one when omitted
`sender`	string	SMS only	Approved SMS sender; uses the account default when omitted
`metaTemplateName`	string	Meta only	Approved template name when a template is required
`metaTemplateLanguage`	string	Meta only	Template language, such as `en_US` or `sw`
`metaTemplateParams`	array	Meta only	Ordered text values for template body parameters

Aliases phone or msisdn may replace to; message may replace text.

Delivery examples

WhatsApp first, SMS fallback

{
  "channels": ["whatsapp_qr", "whatsapp_meta", "sms"],
  "deliveryMode": "fallback"
}

KarFlows tries the list from left to right. A channel is successful only after it returns a real message ID.

SMS only

{
  "channels": ["sms"],
  "deliveryMode": "fallback"
}

WhatsApp QR and SMS together

{
  "channels": ["whatsapp_qr", "sms"],
  "deliveryMode": "all"
}

Unified OTP

Unified OTP is generated and verified by KarFlows. It can deliver the same code by WhatsApp QR, Meta, SMS, or a combination.

Send OTP

POST https://karflows.com/api/omni/otp/send

curl -X POST "https://karflows.com/api/omni/otp/send" \
  -H "Authorization: Bearer kfmsg_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+255700000000",
    "channels": ["whatsapp_qr", "sms"],
    "deliveryMode": "fallback",
    "whatsappFrom": "447405993704",
    "sender": "DM BLUEWAVE",
    "otpLength": 6,
    "expiresIn": 300,
    "template": "Your login code is {{code}}. It expires in {{minutes}} minutes."
  }'

Verify OTP

POST https://karflows.com/api/omni/otp/verify

curl -X POST "https://karflows.com/api/omni/otp/verify" \
  -H "Authorization: Bearer kfmsg_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "pinId": "kfot_...",
    "pin": "123456"
  }'

OTP security

KarFlows protects OTP verification with:

Server-side code generation.
Hashed OTP storage.
Automatic invalidation of an older active OTP sent to the same phone.
Expiry windows.
Attempt limits per pinId.
Rate limits per phone and IP.
Logs for failed, expired, and blocked attempts.

Never include code, pin, or otp in the send request. KarFlows rejects custom OTP codes. otpLength accepts 4 to 8 digits. expiresIn accepts 60 to 3,600 seconds.

Logs

GET https://karflows.com/api/omni/logs?limit=50

curl "https://karflows.com/api/omni/logs?limit=50" \
  -H "Authorization: Bearer kfmsg_your_token"

Logs include every attempted channel, not only the first success. The maximum limit is 200.

Webhooks

Unified Webhooks notify your application when routing, delivery, and OTP events happen. Create them in the customer dashboard under Unified API > Webhooks. Webhooks follow the same plan rule as Unified API, so if Unified API is disabled or the plan expires, webhook management is blocked too.

Available events

Event	Description
`message.sent`	A Unified text message succeeded
`message.failed`	All selected message channels failed
`message.routed`	Routing finished and all channel attempts were logged
`sms.sent`	SMS was used successfully
`sms.failed`	SMS was attempted and failed
`otp.sent`	Unified OTP was accepted by at least one channel
`otp.verified`	OTP verification succeeded
`otp.failed`	OTP delivery or verification failed
`otp.expired`	OTP was verified after expiry

Security headers

Every webhook delivery is signed.

X-KarFlows-Event: message.sent
X-KarFlows-Delivery: kfwh_1778175301000_k9x2abp1
X-KarFlows-Timestamp: 1778175301
X-KarFlows-Signature: sha256=...

Verify the signature using the webhook secret shown when the webhook is created. See the Webhooks reference for full verification examples.

Pagination

Webhook endpoint lists are limited to 20 rows per page inside KarFlows. This keeps the dashboard usable for high-volume customers with many integrations.

Start Here

Messaging APIs

Operations

SDKs

Reference

Unified Messaging API

Endpoint

Headers

Send text

Parameters

Delivery examples

WhatsApp first, SMS fallback

SMS only

WhatsApp QR and SMS together

Unified OTP

Send OTP

Verify OTP

OTP security

Logs

Webhooks

Available events

Security headers

​Endpoint

​Headers

​Send text

​Parameters

​Delivery examples

​WhatsApp first, SMS fallback

​SMS only

​WhatsApp QR and SMS together

​Unified OTP

​Send OTP

​Verify OTP

​OTP security

​Logs

​Webhooks

​Available events

​Security headers

​Pagination

Endpoint

Headers

Send text

Parameters

Delivery examples

WhatsApp first, SMS fallback

SMS only

WhatsApp QR and SMS together

Unified OTP

Send OTP

Verify OTP

OTP security

Logs

Webhooks

Available events

Security headers

Pagination