Chimes

Chimes are notification messages sent to your customers via SMS, WhatsApp, or email. Send order confirmations, payment receipts, shipping updates, and marketing messages with delivery tracking, idempotency guarantees, and flexible sender customization. Built for transactional and marketing workflows that demand reliability—purchase confirmations, status updates, and time-sensitive alerts. For authentication and verification flows that require OTP tokens, use the OTP API instead.

The Chime object

A Chime represents a single notification message sent to one recipient. It captures the complete message lifecycle: creation, transmission, and delivery status. Each Chime links to your application, stores the full message content, recipient contact details, sender information, and tracks transmission through the gateway. Purpose and custom data fields let you categorize and filter Chimes for analytics and debugging.

Properties

Name
created_at
Type
timestamp
Description
When this Chime was created and queued for delivery. Messages typically transmit within seconds of creation.
Name
custom_data
Type
object
Description
Your own key-value string pairs for custom data and tracking. Store user IDs, session identifiers, campaign tags, or any context you need for reconciliation and analytics.
Name
delivery
Type
object|null
Description
Delivery details for this Chime. null until delivery completes. Reserved for future delivery tracking enhancements.
Name
full_message
Type
string
Description
Complete message content that was sent to the recipient. This is exactly what the customer receives, with no template interpolation or formatting changes.
Name
id
Type
string
Description
Unique identifier for this Chime—use it for lookups, delivery tracking, and reconciliation.
Name
purpose
Type
string|null
Description
Purpose of this Chime for categorization and analytics. Common values: receipt, notification, marketing, reminder, shipping_update.
recipientobjectRecipient contact information.Click or tap to expand
- Name
  email
  Type
  object
  Description
  Present when recipient type is email.
  View email attributesClick or tap to expand
  Name
  address
  Type
  string
  Description
  Email address.
- Name
  name
  Type
  string
  Description
  Recipient name for personalization.
- Name
  phone
  Type
  object
  Description
  Present when recipient type is phone.
  View phone attributesClick or tap to expand
  Name
  number
  Type
  string
  Description
  Phone number in international format.
- Name
  type
  Type
  enum
  Description
  Contact type: phone or email.
Name
sender_id
Type
string
Description
Sender identifier shown to the recipient. For SMS, this is the sender ID (alphanumeric or short code). For email, this appears in the "From" field.
transmissionobjectTransmission details and delivery status. null until transmission attempts.Click or tap to expand
- Name
  created_at
  Type
  timestamp
  Description
  When this transmission was initiated.
- Name
  delivered_at
  Type
  timestamp|null
  Description
  When the message was delivered to the recipient. null unless status is delivered.
- Name
  failed_at
  Type
  timestamp|null
  Description
  When the transmission failed. null unless status is failed.
- Name
  sent_at
  Type
  timestamp|null
  Description
  When the message was handed off for delivery. null if not yet sent.
- Name
  sent_via
  Type
  string|null
  Description
  Delivery medium used—sms, whatsapp, or email. null if not yet transmitted.
- Name
  status
  Type
  string
  Description
  Current transmission status—sent, delivered, or failed.

POST/chimes/send

Send Chime

Send a notification message to a single recipient immediately. The message delivers via SMS or email based on the recipient type—phone numbers route to SMS, email addresses route to email. You can override the default transport if needed (e.g., send email to a phone-type recipient). Supports idempotency to prevent duplicate sends during retries.

Use cases

Transaction notifications: Confirm payments, orders, and account changes in real time.
Receipt delivery: Email purchase receipts and invoices after checkout.
Status updates: Notify customers when order status changes or shipments move.
Marketing messages: Send promotional offers, announcements, and campaign messages.
Reminders: Alert customers about upcoming payments, subscription renewals, or cart abandonment.

Required attributes

recipientobjectRecipient contact information.Click or tap to expand
- Name
  type
  Type
  enum
  Description
  Contact type: phone for SMS delivery, email for email delivery.
- Name
  phone
  Type
  object
  Description
  Required when type is phone.
  View phone attributesClick or tap to expand
  Name
  number
  Type
  string
  Description
  Phone number in international format (e.g., +233544998605) or local format. We parse and normalize the number automatically.
- Name
  email
  Type
  object
  Description
  Required when type is email.
  View email attributesClick or tap to expand
  Name
  address
  Type
  string
  Description
  Email address. Must be valid and deliverable.
- Name
  name
  Type
  string
  Description
  Optional. Recipient name for personalization. Displayed in email "To" field or used for message customization.
Name
full_message
Type
string
Description
Complete message content to send. Include the entire text—we don't interpolate templates or add formatting. For SMS, keep under 160 characters to avoid multi-part messages (which cost more and may delay delivery).

Optional attributes

Name
custom_data
Type
object
Description
Your own key-value string pairs. Store user IDs, session tokens, campaign identifiers, or any custom data you need. All keys and values must be strings.
Name
idempotency_key
Type
string
Description
Unique key to prevent duplicate sends. If you retry a request with the same key, we return the original Chime instead of sending again. Auto-generated if you don't provide one. Use this for critical messages like payment confirmations and transaction receipts.
Name
purpose
Type
string
Description
Purpose of this Chime for categorization. Examples: receipt, notification, marketing, reminder, shipping_update. Use this to filter and analyze Chimes in dashboards and reports.
Name
sender_id
Type
string
Description
Sender identifier shown to recipient. For SMS, this is the sender ID (11 characters max, alphanumeric). For email, this appears in the "From" field. Uses your account default if omitted.
Name
transport
Type
enum
Description
Delivery mechanism: sms or email. Defaults to recipient type if not specified. Override this to send email to a phone-type recipient or vice versa (rare but supported).

Request

POST

/chimes/send

curl https://api.zebo.dev/chimes/send \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": {
      "type": "phone",
      "phone": {
        "number": "+233544998605"
      },
      "name": "John Doe"
    },
    "full_message": "Your order #OR-12345 has been shipped and will arrive in 2-3 business days. Track at: https://track.example.com/OR-12345",
    "sender_id": "YourBrand",
    "purpose": "shipping_update",
    "custom_data": {
      "user_id": "usr_abc123",
      "flow": "signup"
    }
  }'

{
  "chime": {
    "id": "ch_WkPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYU",
    "created_at": "2025-12-10T10:30:00Z",
    "full_message": "Your order #OR-12345 has been shipped and will arrive in 2-3 business days. Track at: https://track.example.com/OR-12345",
    "recipient": {
      "type": "phone",
      "phone": {
        "number": "+233544998605"
      },
      "name": "John Doe"
    },
    "sender_id": "YourBrand",
    "purpose": "shipping_update",
    "custom_data": {
      "order_id": "or_abc123",
      "fulfillment_id": "ffl_xyz789"
    },
    "delivery": null,
    "transmission": {
      "created_at": "2025-12-10T10:30:00Z",
      "sent_via": "sms",
      "status": "sent",
      "sent_at": "2025-12-10T10:30:05Z",
      "delivered_at": null,
      "failed_at": null
    }
  }
}

POST/chimes/lookup

Lookup Chime

Retrieve the complete details of a previously sent Chime by its ID. Returns the full Chime object including transmission status, delivery details, and all custom data you attached during creation. Use this endpoint to track message delivery, verify sends during support requests, and reconcile Chimes with your internal systems.

Required attributes

Name
chime_id
Type
string
Description
Unique identifier of the Chime to retrieve.

Request

POST

/chimes/lookup

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

Response

{
  "chime": {
    "id": "ch_WkPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYU",
    "created_at": "2025-12-10T10:30:00Z",
    "full_message": "Your order #OR-12345 has been shipped and will arrive in 2-3 business days. Track at: https://track.example.com/OR-12345",
    "recipient": {
      "type": "phone",
      "phone": {
        "number": "+233544998605"
      },
      "name": "John Doe"
    },
    "sender_id": "YourBrand",
    "purpose": "shipping_update",
    "custom_data": {
      "order_id": "or_abc123",
      "fulfillment_id": "ffl_xyz789"
    },
    "delivery": null,
    "transmission": {
      "created_at": "2025-12-10T10:30:00Z",
      "sent_via": "sms",
      "status": "delivered",
      "sent_at": "2025-12-10T10:30:05Z",
      "delivered_at": "2025-12-10T10:30:15Z",
      "failed_at": null
    }
  }
}

POST/chimes/schedule

Schedule Chime

Schedule a notification message for delivery at a specific future time. Send to a single recipient or broadcast to multiple recipients. Recipients are validated at send time, not when you schedule—if a recipient is invalid or unreachable, you'll see the failure when the Chime attempts delivery.

Required attributes

Name
full_message
Type
string
Description
Complete message content to send when the scheduled time arrives. Include the entire text—we don't interpolate templates or add formatting.
Name
recipients
Type
array
Description
Array of recipient addresses—phone numbers in international format (e.g., +233544998605) or email addresses. We don't validate these until send time, so invalid recipients will fail when we attempt delivery.
Name
send_after
Type
timestamp
Description
When to send the Chime. Must be in the future. Messages are queued and sent shortly after this time—expect delivery within seconds to minutes after the scheduled time.

Optional attributes

Name
idempotency_key
Type
string
Description
Unique key to prevent duplicate scheduling. If you retry with the same key, we return the original schedule instead of creating a new one. Auto-generated if omitted.
Name
purpose
Type
string
Description
Purpose of this Chime for categorization. Examples: reminder, marketing, notification, shipping_update.
Name
sender_id
Type
string
Description
Sender identifier shown to recipients. For SMS, this is the sender ID (11 characters max, alphanumeric). For email, this appears in the "From" field. Uses your account default if omitted.

Request

POST

/chimes/schedule

curl https://api.zebo.dev/chimes/schedule \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      "+233544998605",
      "+233501234567"
    ],
    "full_message": "Reminder: Your subscription renews tomorrow. Visit https://example.com/billing to update payment details.",
    "send_after": "2025-12-15T09:00:00Z",
    "sender_id": "YourBrand",
    "purpose": "reminder"
  }'

Response

{
  "scheduled_chime": {
    "id": "chs_kPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYUWk",
    "application_id": "app_abc123xyz",
    "created_at": "2025-12-10T14:30:00Z",
    "recipients": [
      "+233544998605",
      "+233501234567"
    ],
    "full_message": "Reminder: Your subscription renews tomorrow. Visit https://example.com/billing to update payment details.",
    "sender_id": "YourBrand",
    "purpose": "reminder",
    "send_after": "2025-12-15T09:00:00Z"
  }
}

POST/schedules/lookup

Lookup a scheduled Chime

Retrieve a scheduled Chime and check its execution status. Returns the schedule details, IDs of all Chimes created when it executed, and any delivery failures. Use this to track broadcast delivery success, debug failed recipients, or verify cancellation status.

Required attributes

Name
schedule_id
Type
string
Description
The schedule ID returned when you created the scheduled Chime. Example: sch_kPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYUWk.

Request

POST

/schedules/lookup

curl https://api.zebo.dev/schedules/lookup \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule_id": "sch_kPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYUWk"
  }'

Response

{
  "scheduled_chime": {
    "id": "sch_kPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYUWk",
    "recipients": [
      "+233544998605",
      "+233501234567",
      "+233509999999"
    ],
    "content": "Reminder: Your subscription renews tomorrow. Visit https://example.com/billing to update payment details.",
    "sender_id": "YourBrand",
    "purpose": "reminder",
    "send_after": "2025-12-15T09:00:00Z",
    "created_at": "2025-12-10T14:30:00Z",
    "executed_at": "2025-12-15T09:00:03Z",
    "chime_ids": [
      "ch_abc123xyz",
      "ch_def456uvw"
    ],
    "errors": [
      {
        "recipient": "+233509999999",
        "type": "invalid_phone_number",
        "fix_code": "f-change_request_parameters"
      }
    ]
  }
}

POST/schedules/cancel

Cancel a scheduled Chime

Cancel a pending scheduled Chime before it executes. Prevents message delivery if called before the send_after time. Returns an error if the schedule already executed or was previously canceled. Idempotent—safe to retry.

Rules

Only works on pending schedules (not yet executed)
Cannot cancel after executed_at is set
Cannot cancel schedules that are already canceled

Required attributes

Name
schedule_id
Type
string
Description
The schedule ID to cancel. Must be a pending schedule that hasn't executed yet.

Request

POST

/schedules/cancel

curl https://api.zebo.dev/schedules/cancel \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule_id": "sch_kPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYUWk"
  }'

Response

{
  "scheduled_chime": {
    "id": "sch_kPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYUWk",
    "recipients": [
      "+233544998605",
      "+233501234567"
    ],
    "content": "Reminder: Your subscription renews tomorrow. Visit https://example.com/billing to update payment details.",
    "sender_id": "YourBrand",
    "purpose": "reminder",
    "send_after": "2025-12-15T09:00:00Z",
    "created_at": "2025-12-10T14:30:00Z",
    "canceled_at": "2025-12-14T16:45:00Z",
    "chime_ids": [],
    "errors": []
  }
}

POST/chimes/broadcast

Broadcast Chimes

Send immediate notifications to multiple recipients. Unlike scheduled Chimes, broadcasts execute within seconds of creation. Perfect for urgent announcements, order confirmations, or time-sensitive alerts. Each recipient receives an individual message.

Request body

idempotency_key - Unique key to prevent duplicate broadcasts during retries. Optional but recommended.
message_template required - The message content to send to all recipients.
purpose - Category or intent (e.g., "order_notification", "marketing"). Helps with tracking and analytics.
recipients required - Array of phone numbers (E.164 format) or email addresses. Maximum 4,096 recipients per broadcast.
sender required - Sender identifier displayed to recipients.

Request

POST

/chimes/broadcast

curl https://api.zebo.dev/chimes/broadcast \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      "+233544998605",
      "+233501234567"
    ],
    "message_template": "Your order #12345 has shipped! Track: https://track.shop.com/abc123",
    "sender": "ShopName",
    "purpose": "order_notification"
  }'

Response

{
  "broadcast": {
    "id": "brc_kPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYUWk",
    "recipients": [
      "+233544998605",
      "+233501234567"
    ],
    "content": "Your order #12345 has shipped! Track: https://track.shop.com/abc123",
    "sender_id": "ShopName",
    "purpose": "order_notification",
    "send_after": "2025-12-15T09:00:00Z",
    "created_at": "2025-12-15T09:00:00Z"
  }
}

POST/broadcasts/lookup

Lookup a broadcast

Retrieve a broadcast and check its execution status. Returns the broadcast details, IDs of all Chimes created when it executed, and any delivery failures. Use this to track delivery success, debug failed recipients, or verify cancellation status.

Required attributes

Name
broadcast_id
Type
string
Description
The broadcast ID returned when you created the broadcast. Example: brc_kPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYUWk.

Request

POST

/broadcasts/lookup

curl https://api.zebo.dev/broadcasts/lookup \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "broadcast_id": "brc_kPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYUWk"
  }'

Response

{
  "broadcast": {
    "id": "brc_kPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYUWk",
    "recipients": [
      "+233544998605",
      "+233501234567",
      "+233509999999"
    ],
    "content": "Your order #12345 has shipped! Track: https://track.shop.com/abc123",
    "sender_id": "ShopName",
    "purpose": "order_notification",
    "send_after": "2025-12-15T09:00:00Z",
    "created_at": "2025-12-15T09:00:00Z",
    "executed_at": "2025-12-15T09:00:03Z",
    "chime_ids": [
      "ch_abc123xyz",
      "ch_def456uvw"
    ],
    "errors": [
      {
        "recipient": "+233509999999",
        "type": "invalid_phone_number",
        "fix_code": "f-change_request_parameters"
      }
    ]
  }
}

POST/broadcasts/cancel

Cancel a broadcast

Cancel a pending broadcast before it executes. Since broadcasts execute within seconds, cancellation only works if called immediately after creation. Returns an error if the broadcast already executed or was previously canceled. Idempotent—safe to retry.

Rules

Only works on pending broadcasts (not yet executed)
Cannot cancel after executed_at is set
Cannot cancel broadcasts that are already canceled
Narrow time window (typically <5 seconds)

Required attributes

Name
broadcast_id
Type
string
Description
The broadcast ID to cancel. Must be a pending broadcast that hasn't executed yet.

Request

POST

/broadcasts/cancel

curl https://api.zebo.dev/broadcasts/cancel \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "broadcast_id": "brc_kPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYUWk"
  }'

Response

{
  "broadcast": {
    "id": "brc_kPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYUWk",
    "recipients": [
      "+233544998605",
      "+233501234567"
    ],
    "content": "Your order #12345 has shipped! Track: https://track.shop.com/abc123",
    "sender_id": "ShopName",
    "purpose": "order_notification",
    "send_after": "2025-12-15T09:00:00Z",
    "created_at": "2025-12-15T09:00:00Z",
    "canceled_at": "2025-12-15T09:00:02Z",
    "chime_ids": [],
    "errors": []
  }
}