LogoZebo Studio

Chime

Chime delivers transactional and marketing notifications to your customers through SMS and email. Every message has an inspectable transmission status, and stable idempotency keys protect retries from duplicate sends. Use Chimes for order confirmations, payment receipts, shipping updates, appointment reminders, and promotional campaigns.

Why Chime matters

One API for supported messaging channels

Use one API for SMS and email notifications. Inline recipients identify their contact type explicitly, while saved-customer recipients select SMS or email and let Commerce resolve the corresponding contact.

Guaranteed delivery tracking

Every Chime tracks its transmission lifecycle: initialized, sent, delivered, or failed. Query a Chime by ID to inspect current status, investigate 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 request_meta.idempotency_key or the Idempotency-Key header 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:

  • initialized – Transmission created but not yet sent
  • 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 request_meta.idempotency_key or the Idempotency-Key header 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 $COMMERCE_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 using POST /chimes/broadcast. Inline recipient objects use type plus a matching phone.number or email.address; saved-customer recipients use transport plus customer_id. Each recipient receives an individual message—no shared threads or group texts.

curl https://api.zebo.dev/chimes/broadcast \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -d '{
    "recipients": [
      { "type": "phone", "phone": { "number": "+233544998605" } },
      { "type": "phone", "phone": { "number": "+233501234567" } },
      { "type": "phone", "phone": { "number": "+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. Inline recipient objects use type plus a matching phone.number or email.address; saved-customer recipients use transport plus customer_id. Commerce resolves and validates every recipient before accepting the schedule.

curl https://api.zebo.dev/chimes/schedule \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -d '{
    "recipients": [
      { "type": "phone", "phone": { "number": "+233544998605" } },
      { "type": "phone", "phone": { "number": "+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"
  }'

send_after controls when a scheduled Chime becomes eligible to execute; it is not a delivery-time guarantee. A malformed or unresolved recipient rejects the schedule, while later transmission failures remain isolated to the affected recipient. Visit POST /chimes/schedule 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 $COMMERCE_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 $COMMERCE_API_KEY" \
  -H "Idempotency-Key: cancel-schedule-kPvqTrqGsopu07wf" \
  -d '{
    "schedule_id": "sch_kPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYUWk"
  }'

Cancellation only works on pending schedules. You cannot cancel a schedule that already executed or was previously canceled. A network retry is safe only when it reuses the same Idempotency-Key; a new cancellation request after cancellation returns an error. Visit POST /schedules/cancel for 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 $COMMERCE_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 request_meta.idempotency_key or the Idempotency-Key header.

POST /chimes/broadcast – Send immediate notifications to one or more recipients. Returns a broadcast object with an ID. The API requires at least one recipient and does not publish a fixed maximum.

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 an error if already executed or canceled; same-key retries replay the original result.

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?