Send customer notifications

Send order confirmations, payment receipts, shipping updates, and reminders to your customers via SMS, WhatsApp, or email. Chime handles delivery tracking, idempotency, and gateway routing so you can focus on crafting the right message at the right time. This guide shows you how to notify customers immediately or schedule messages for future delivery.

How it works

Notifications work in two phases: create the Chime with your message content and recipient details, then query delivery status when you need confirmation. Messages send immediately or at a scheduled time. Chime automatically routes SMS to phone numbers and email to email addresses without requiring gateway configuration. Every Chime tracks its transmission lifecycle—queued, sent, delivered, or failed—so you always know whether customers received your notification.

Step 1: Send a notification immediately

Send a notification right away when order status changes, payment completes, or any event requires immediate customer awareness. Call POST /chimes/send with the recipient contact, message content, and optional metadata.

curl https://api.zebo.dev/chimes/send \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": {
      "type": "phone",
      "phone": {
        "number": "+233544998605"
      },
      "name": "Gloria Kesewaa"
    },
    "full_message": "Your order #OR-7821 has been confirmed. Total: GHS 200.00. Expected delivery: Dec 18-20. Track here: https://checkout.zebo.dev/track/OR-7821",
    "sender": "YourStore",
    "purpose": "notification",
    "idempotency_key": "notify_order_OR-7821_confirmed",
    "custom_data": {
      "order_id": "OR-7821",
      "event": "order_confirmed",
      "customer_id": "cu_gloria_k"
    }
  }'

The Chime API responds immediately with a Chime ID and initial transmission status. Actual delivery happens asynchronously—SMS typically delivers within seconds, email within a minute.

Using idempotency keys

Pass idempotency_key to prevent duplicate notifications during retries. If your server crashes after sending but before recording the send, retry with the same key—Chime returns the original notification instead of sending again. This protects customers from receiving confusing duplicate messages for payment confirmations, order updates, and other critical events.

Attaching metadata

Use custom_data to link notifications back to your internal records. Store order IDs, customer IDs, event types, or any context you need for analytics and debugging. Query Chimes later to retrieve this metadata for reconciliation or support investigations.

Step 2: Check delivery status

Verify notification delivery by calling POST /chimes/lookup with the Chime ID. The response includes transmission status, delivery timestamps, and all metadata from creation.

curl https://api.zebo.dev/chimes/lookup \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chime_id": "WkPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYU"
  }'

Status values indicate message progress: sent means the message left our system but delivery isn't confirmed yet, delivered means the customer's device received it, and failed means delivery couldn't complete (invalid number, carrier rejection, or recipient unreachable).

Schedule notifications for future delivery

Schedule Chimes when you need notifications delivered at specific future times—subscription renewal reminders, appointment confirmations, or time-based marketing campaigns. Call POST /chimes/schedule with the message, recipients, and send_after timestamp.

curl https://api.zebo.dev/chimes/schedule \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      "+233544998605",
      "+233501234567"
    ],
    "full_message": "Reminder: Your subscription renews in 3 days on Dec 18. Update payment details at https://checkout.zebo.dev/billing or contact support.",
    "send_after": "2025-12-15T09:00:00Z",
    "sender_id": "YourBrand",
    "purpose": "reminder"
  }'

Scheduled Chimes deliver at or shortly after the specified time. Recipients aren't validated until send time—invalid phone numbers or email addresses fail when delivery is attempted, not when you schedule.

Crafting effective notifications

Front-load critical information

Put order numbers, amounts, dates, or urgency first. "Order #OR-7821 shipped. Arrives Dec 18-20" beats "We're excited to inform you that your recent order has been shipped and should arrive soon."

Include actionable links

Always provide next steps: order tracking URLs, payment confirmation pages, or support contact forms. Make URLs meaningful—checkout.zebo.dev/track/OR-7821 tells customers where they're going before they click.

Keep SMS under 160 characters

SMS charges per 160-character segment. Long messages split across multiple texts and confuse recipients. If you need more space, use email instead or shorten the message and link to details.

Use idempotency for critical messages

Payment confirmations, order receipts, and account alerts demand idempotency. Pass a unique idempotency_key constructed from the event—notify_payment_${payment_id}_confirmed—to prevent duplicate notifications during retries.

Next steps

• Chime API Reference — Complete endpoint documentation and response formats
• Product: Chime — Deep dive into Chime features and use cases
• OTP API — Send verification codes for authentication flows
• Orders — Trigger notifications from order events