How To Use This Platform

Client integration guide for tenant onboarding, template policies, channel payloads, bulk sends, delivery tracking, and production readiness.

WhatsApp template mandatory Other channels template optional Bulk rules same as single send Provider details abstracted

1. Quickstart (First Successful Send)

  1. Create account at /portal/signup.
  2. Store API key in server-side secret storage.
  3. Create one template for WhatsApp or use raw payload for Email/SMS/Slack/Voice.
  4. Send a notification using POST /api/v1/notifications/send.
  5. Use returned notification_id to track status via GET /api/v1/notifications/{notification_id}.
Goal: verify end-to-end flow once before integrating business events.

2. Authentication

All tenant API calls must include tenant key:

X-API-Key: your_tenant_api_key

Minimum send request

POST /api/v1/notifications/send
Content-Type: application/json
X-API-Key: your_tenant_api_key
Use API keys only from backend services. Do not expose keys in browser/mobile client bundles.

3. Template Policy (Important)

Channel Template Required Can Send Raw Body Notes
whatsapp Yes No Provide template_id and variables in data.
email, sms, slack, voice No Yes Either template mode or raw mode is valid.

Check runtime channel metadata via GET /api/v1/channels/capabilities.

4. Channel Cookbook (Minimal Payloads)

Email raw mode

{
  "recipient": {"email": "user@example.com"},
  "notification": {
    "channels": ["email"],
    "subject": "Order Update",
    "body": "Your order shipped",
    "data": {"order_id": "ORD-1001"}
  }
}

SMS raw mode

{
  "recipient": {"phone": "+14155550123"},
  "notification": {
    "channels": ["sms"],
    "body": "Your OTP is 549921"
  }
}

Slack template mode (optional)

{
  "recipient": {"slack_user_id": "U123456"},
  "notification": {
    "channels": ["slack"],
    "template_id": "slack_ops_alert",
    "data": {"service": "payments", "severity": "high"}
  }
}

WhatsApp template mode (required)

{
  "recipient": {"phone": "+14155550123"},
  "notification": {
    "channels": ["whatsapp"],
    "template_id": "wa_order_update",
    "data": {"name": "Alex", "order_id": "ORD-1001"}
  }
}
If channels contains whatsapp and template_id is missing, request will fail.

5. Bulk Messaging

Bulk flow follows the same template policy as single send.

  1. Use bulk endpoint from your integration layer.
  2. If any selected channel is whatsapp, include template_id.
  3. For other channels, choose template mode or raw mode.
  4. Pass recipient-level fields and variables per row/object.

Bulk template mode idea

{
  "channels": ["whatsapp", "email"],
  "template_id": "order_confirmation",
  "recipients": [
    {"phone": "+14155550123", "email": "a@example.com", "data": {"name": "Alex"}},
    {"phone": "+14155550124", "email": "b@example.com", "data": {"name": "Sam"}}
  ]
}
Rule remains: mandatory only for WhatsApp, optional for all other channels, including bulk.

6. Delivery Tracking

  1. Capture notification_id from send response.
  2. Fetch status via GET /api/v1/notifications/{notification_id}.
  3. Use tenant dashboard for recent activity by channel, recipient, status, and attempts.

Status meanings

Status Meaning Action
queued Accepted by platform, waiting dispatch. No action.
sent Handed to channel/provider. Wait for delivery update.
delivered Delivery confirmed. No action.
failed Dispatch or provider failure. Inspect reason, fix payload/template, retry with idempotency key.

7. Common Errors and Fixes

Error Pattern Cause Fix
Missing template_id for WhatsApp Policy violation Include template_id and required variables in data.
Template variable mismatch Payload data keys do not match placeholders Align template placeholders and payload data fields.
Unauthorized / invalid API key Wrong or revoked key Use active tenant key and ensure header is X-API-Key.
Recipient field missing Channel requires specific recipient identity Use required field from channel capability endpoint.

8. Production Checklist

  • Store API keys in secret manager, not in source code.
  • Always send idempotency_key for transactional events.
  • Pre-validate channel payload using /api/v1/channels/capabilities.
  • Maintain fallback channel strategy for high-priority events.
  • Monitor failed deliveries and alert on threshold breaches.
  • Version templates and roll out changes gradually.

9. Mapping From Twilio/Mailgun Thinking

  • Twilio WhatsApp style: choose template id + variables at send time.
  • Mailgun style: template mode for campaigns or raw mode for direct content.
  • This platform combines both patterns in one tenant API with channel-aware policy enforcement.
Tenant users focus on business payload and delivery outcome. Provider-specific details are managed internally by the platform.