LogoZebo Studio

Chime

Chime delivers transactional and marketing notifications to your customers via SMS, WhatsApp, and email. Built for reliability—every message is tracked from creation through delivery with idempotency guarantees and comprehensive delivery status. Send order confirmations, payment receipts, shipping updates, appointment reminders, and promotional campaigns without managing gateway integrations or delivery infrastructure.

Why Chime matters

One API for all messaging channels

Stop integrating with multiple SMS gateways, email providers, and WhatsApp business accounts. Chime handles routing, failover, and delivery tracking across all channels. You send messages to phone numbers or email addresses—we determine the optimal delivery path based on recipient type, cost, and reliability.

Guaranteed delivery tracking

Every Chime tracks its complete lifecycle: queued, transmitted, delivered, or failed. No messages disappear into void. Query any Chime by ID to verify delivery, debug customer support issues, or reconcile campaigns against your internal systems.

Idempotency prevents duplicate sends

Network failures and timeout retries can't create duplicate notifications. Pass an idempotency_key with critical messages like payment confirmations, password resets, or transaction receipts. If you retry the same request, Chime returns the original message instead of sending again—customers never receive confusing duplicates.

Built for high-volume campaigns

Send thousands of messages without rate limit concerns. Perfect for bulk campaigns (product launches, flash sales, service announcements) and high-throughput transactional workflows (order confirmations, mass appointment reminders).

Understanding Chime

Chime solves notification delivery for commerce applications. Use it whenever you need to inform customers about transactions, status changes, or time-sensitive events—order confirmations, payment receipts, shipping updates, appointment reminders, promotional campaigns, and account alerts. Chime handles routing, delivery tracking, and reliability concerns for both high-volume marketing campaigns and critical transactional workflows. Contact support if you're uncertain whether Chime is appropriate for your use case.

Chime supports both immediate and scheduled delivery. Send messages right away for real-time notifications or schedule them for future delivery—subscription renewal reminders, appointment confirmations, or time-based marketing campaigns.

When NOT to use Chime

Authentication and verification flows

Don't use Chime for one-time password (OTP) delivery, two-factor authentication codes, or identity verification tokens. These flows demand specialized handling. Use the OTP API instead—it's purpose-built for verification workflows.

Real-time chat and conversations

Chime delivers one-way notifications, not bidirectional conversations. If customers need to reply or engage in back-and-forth communication, integrate a dedicated messaging platform. Chime lacks read receipts, typing indicators, conversation threading, and reply handling.

Time-critical alerts requiring immediate delivery

Message delivery depends on carrier networks and recipient device availability. For fraud alerts, account takeover prevention, or other scenarios requiring guaranteed immediate delivery, consider in-app push notifications or dedicated alerting infrastructure.

How Chime works

Message creation and delivery

When you call the Send Chime endpoint, Commerce creates a Chime record and returns an immediate response with Chime ID. Delivery happens asynchronously—SMS for phone numbers, email for email addresses.

Delivery tracking

Query transmission status via the Lookup Chime endpoint. The response includes:

  • sent – Message sent, awaiting delivery confirmation
  • delivered – Message successfully delivered to recipient
  • failed – Delivery failed (invalid number, carrier rejection, or other error)

Check delivery status periodically for campaigns or on-demand during support investigations.

Idempotency handling

Pass idempotency_key to prevent duplicate sends. If you retry with the same key, Commerce returns the original Chime instead of creating and sending a new one. This protects against accidental duplicate sends during network failures, timeout retries, or user double-clicks.

Sending immediate Chimes

Send notifications immediately by calling POST /chimes/send with recipient information, message content, and optional metadata:

curl https://api.zebo.dev/chimes/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "recipient": {
      "type": "phone",
      "phone": {"number": "+233241234567"}
    },
    "full_message": "Reminder: Your appointment with Dr. Mensah is tomorrow, Dec 15 at 3:00 PM. Location: Accra Medical Center. To reschedule: https://clinic.com/apt/789",
    "sender_id": "ClinicName",
    "purpose": "reminder",
    "custom_data": {
      "appointment_id": "apt_789",
      "doctor_id": "doc_123",
      "reminder_type": "day_before"
    }
  }'

Visit the POST /chimes/send endpoint documentation to learn about all available parameters, response formats, and error handling.

Broadcasting to multiple recipients

Send immediate notifications to multiple recipients simultaneously using POST /chimes/broadcast. Perfect for urgent announcements, order confirmations, flash sales, or time-sensitive alerts that need to reach many customers instantly. Each recipient receives an individual message—no shared threads or group texts.

curl https://api.zebo.dev/chimes/broadcast \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "recipients": [
      "+233544998605",
      "+233501234567",
      "+233208765432"
    ],
    "message_template": "Your order #12345 has shipped! Track at https://shop.com/track/abc123 - estimated delivery: tomorrow by 5PM.",
    "sender": "ShopBrand",
    "purpose": "order_notification"
  }'

Visit the POST /chimes/broadcast endpoint documentation for complete parameter details. Use POST /broadcasts/lookup to track execution status and identify failed recipients. Cancel pending broadcasts with POST /broadcasts/cancel if needed—though broadcasts execute immediately, so cancellation only works within seconds of creation.

Scheduling Chimes for future delivery

Schedule Chimes for delivery at specific future times using POST /chimes/schedule. Send to a single recipient or broadcast to multiple recipients. Perfect for subscription renewal reminders, appointment confirmations, marketing campaign launches, or any time-based notification workflow.

curl https://api.zebo.dev/chimes/schedule \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "recipients": [
      "+233544998605",
      "+233501234567"
    ],
    "full_message": "Reminder: Your annual subscription renews in 7 days. Update payment details at https://billing.com/sub/123 or contact support.",
    "send_after": "2025-12-20T09:00:00Z",
    "sender_id": "BillingTeam",
    "purpose": "reminder"
  }'

Scheduled Chimes are delivered at or shortly after the specified time. Recipient validation happens at send time, not when you schedule—invalid or unreachable recipients fail when delivery is attempted. Visit the POST /chimes/schedule endpoint documentation for complete parameter details and response formats.

Managing scheduled Chimes

Checking schedule status

Track scheduled Chime execution and delivery using POST /schedules/lookup. Returns the schedule details, all created Chimes after execution, and any per-recipient delivery failures. Perfect for monitoring broadcast campaigns, debugging failed recipients, or verifying delivery completion:

curl https://api.zebo.dev/schedules/lookup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "schedule_id": "sch_kPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYUWk"
  }'

The response includes all created Chimes with transmission status, per-recipient errors with fix codes, and execution timestamps. Visit the POST /schedules/lookup endpoint documentation for complete response structure.

Canceling scheduled Chimes

Cancel pending schedules before execution using POST /schedules/cancel. Prevents delivery if called before the send_after time. Returns an error if the schedule already executed or was previously canceled. Perfect for handling customer opt-outs, correcting scheduling mistakes, or stopping broadcasts that are no longer relevant:

curl https://api.zebo.dev/schedules/cancel \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "schedule_id": "sch_kPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYUWk"
  }'

Cancellation only works on pending schedules—schedules that haven't executed yet. You cannot cancel schedules that already executed or were previously canceled. The operation is idempotent, so retrying a cancellation is safe. Visit the POST /schedules/cancel endpoint documentation for error scenarios and response details.

Looking up Chimes

Retrieve Chime details anytime after creation using POST /chimes/lookup. Query by Chime ID to check delivery status, view transmission details, or retrieve custom metadata:

curl https://api.zebo.dev/chimes/lookup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "id": "ch_abc123xyz"
  }'

The lookup response includes complete Chime details: recipient information, message content, transmission status, delivery timestamps, and any custom metadata attached during creation. Visit the POST /chimes/lookup endpoint documentation for complete response schemas and status values.

Message content guidelines

Keep SMS under 160 characters

SMS charges per 160-character segment. Long messages arrive split across multiple texts—confusing for recipients.

Include actionable links

Always provide next steps: order tracking URLs, cart resume links, appointment rescheduling pages, or support contact forms. Make URLs short—use link shorteners if needed to preserve character budget.

Personalize with recipient name

Messages addressing customers by name perform better. Pass name in recipient object and include it in message content.

Front-load critical information

Put order numbers, amounts, dates, or urgency signals early in the message. "Order #12345 shipped" is clearer than "We wanted to let you know that your order has shipped."

Avoid spam trigger words

Certain phrases trigger carrier spam filters: "FREE", "Click now", "Limited time", "Act fast", "Congratulations". Use sparingly or rephrase.

Custom Data and analytics

Attach metadata for tracking

Use custom_data to link Chimes to your internal records. Store order IDs, customer IDs, campaign identifiers, session tokens, or any context you need. All keys and values must be strings.

{
  "custom_data": {
    "order_id": "order_12345",
    "customer_id": "cust_789",
    "campaign": "holiday_2024",
    "cohort": "high_value",
    "ab_test_variant": "control"
  }
}

Query Chimes later by ID to retrieve Custom Data—useful for reconciliation, analytics, and debugging.

Categorize with purpose

Use purpose field consistently across Chimes for classification. Common values: receipt, notification, marketing, reminder, shipping_update, security_alert. Build dashboards and reports by grouping on purpose.

Build delivery analytics

Track Chime delivery rates by querying /chimes/lookup for campaign Chimes. Calculate sent vs delivered percentages, identify failed numbers, and optimize future campaigns based on delivery patterns.

API operations

The Chime API provides nine endpoints for sending, scheduling, broadcasting, and managing notifications:

Immediate delivery

POST /chimes/send – Send a notification to a single recipient immediately. Returns Chime object with ID and transmission status. Supports idempotency via idempotency_key parameter.

POST /chimes/broadcast – Send immediate notifications to multiple recipients. Returns broadcast object with ID and begins delivery within seconds. Maximum 4,096 recipients per broadcast.

POST /chimes/lookup – Retrieve individual Chime details by ID. Returns complete Chime object including transmission status, delivery details, and custom metadata.

Scheduled delivery

POST /chimes/schedule – Schedule notifications for future delivery to single or multiple recipients. Returns scheduled Chime object with schedule ID and delivery time.

POST /schedules/lookup – Retrieve scheduled Chime details, execution status, and created Chime IDs. Returns schedule details plus IDs of all delivered messages and any delivery failures.

POST /schedules/cancel – Cancel a pending scheduled Chime before execution. Returns error if already executed or canceled. Idempotent.

Broadcast management

POST /broadcasts/lookup – Retrieve broadcast details, execution status, and created Chime IDs. Returns broadcast details plus all delivered message IDs and failures.

POST /broadcasts/cancel – Cancel a pending broadcast before execution. Narrow time window (typically <5 seconds). Returns error if already executed or canceled.

Full API reference: Chime API documentation

Next steps

  • Chime API Reference — Complete endpoint documentation and response formats
  • OTP API — Send verification codes and authentication tokens
  • Orders — Trigger Chimes from order events and status changes

Was this page helpful?