---
title: "Send customer notifications"
description: "Keep customers informed with transactional and marketing notifications via SMS and email using the Chime API."
canonical: "https://studio.inttegro.com/guides/send-customer-notification"
format: inttegro-machine-docs/v1
language: "Python"
sdk_version: "v12.0.0"
reader_profile: optional
reader_manifest: "https://studio.inttegro.com/machine/python/readers/index.json"
reader_identification: "Optional: declare your client only if known and your current-session capabilities; use reader_manifest for supplemental recommendations."
preamble_estimated_tokens: 550
model_token_report: "https://studio.inttegro.com/machine/token-report.json"
preamble_questions: 5
preamble_source: "curated"
recommended_mcp_tools: ["send_customer_sms","get_message","list_messages"]
estimated_tokens: 2934
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** Send an immediate SMS or email Chime to one valid recipient, save its ID, and read transmission state before claiming delivery; authentication codes belong to OTP instead.

### Five questions

#### Q1. How is one recipient specified?

For an inline contact, use its type plus matching phone or email details. For a saved customer, use its customer ID and chosen transport; do not combine saved-customer transport with inline contact fields. [Send chime](https://studio.inttegro.com/machine/python/api/chimes.md#send-chime) owns the exact contract.

#### Q2. Does a returned Chime ID prove delivery?

No. The initial status can be initialized or sent without confirmed delivery. Save the ID and [lookup the Chime](https://studio.inttegro.com/machine/python/api/chimes.md#lookup-chime) to distinguish delivered from failed or still in progress.

#### Q3. Should a receipt or verification code use the same operation?

For an order receipt, send only after a paid state; [Orders](https://studio.inttegro.com/machine/python/api/orders.md) owns that check. Do not use a Chime as an authentication token: the [OTP API](https://studio.inttegro.com/machine/python/api/otps.md) handles expiry, verification, and rate limits.

#### Q4. When does the selected SDK replace wire field names?

The guide's CodeGroup contains direct HTTP examples across language tabs. For a native official SDK call, take its verified parameter and response types from [Send chime](https://studio.inttegro.com/machine/python/api/chimes.md#send-chime); do not infer method members from JSON snippets.

#### Q5. What can MCP send safely?

[send_customer_sms](https://studio.inttegro.com/machine/python/inttegro-mcp/tools.md#send_customer_sms) can send one confirmed SMS of at most 120 characters to an existing customer—not an arbitrary number, email, broadcast, or schedule. [get_message](https://studio.inttegro.com/machine/python/inttegro-mcp/tools.md#get_message) or [list_messages](https://studio.inttegro.com/machine/python/inttegro-mcp/tools.md#list_messages) help review delivery; email or other sends use the trusted [Chimes API](https://studio.inttegro.com/machine/python/api/chimes.md).

## Document content

# Send customer notifications

Send order confirmations, payment receipts, shipping updates, and reminders to your customers by SMS or email. Chime tracks delivery status from creation through delivery. This guide shows you how to notify customers immediately or schedule messages for future delivery.

> Mcp Guide Callout is interactive content. Use the canonical page to view it.

> **Note:**
>
> **Don't use Chimes for verification codes.** If you need to authenticate or
> verify users with one-time passwords, use the [OTP API](https://studio.inttegro.com/machine/python/api/otps.md) instead. The
> OTP API handles token generation, expiry, validation, and rate
> limiting—critical security features that Chimes doesn't provide. See [Verify
> customers with OTP](https://studio.inttegro.com/machine/python/guides/verify-with-otp.md) to learn how to implement secure
> authentication flows.

## 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 routes SMS to phone numbers and email to email addresses. Every Chime tracks its transmission lifecycle—from `'initialized'` through `'sent'` to `'delivered'` or `'failed'`—so you can determine whether a transmission has started and whether delivery was confirmed.

For email recipients, use an email recipient and put the plain-text body in [`full_message`](https://python.inttegro.dev/v12.0.0/inttegro/chime.html#SendRequest.full_message). Inttegro validates the sender and scans message content before delivery.

```python
inttegro.chime.SendRequest(
  recipient=inttegro.chime.InlineRecipientInputVariant2(
    type=inttegro.chime.RecipientType.EMAIL,
    email=inttegro.chime.InlineRecipientInputVariant2Email(
      address="gloria@example.com",
    ),
  ),
  full_message="Your receipt is ready. View it at https://yourstore.example/receipts/or_7821.",
  transport="email",
  sender="YourStore",
)
```

## 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 [Send chime](https://studio.inttegro.com/machine/python/api/chimes.md#send-chime) with one of two recipient shapes: use [`recipient.type`](https://python.inttegro.dev/v12.0.0/inttegro/chime.html#SavedCustomerRecipientInput.type) plus the matching [`recipient.phone.number`](https://python.inttegro.dev/v12.0.0/inttegro/chime.html#InlineRecipientInputVariant1Phone.number) or [`recipient.email.address`](https://python.inttegro.dev/v12.0.0/inttegro/chime.html#InlineRecipientInputVariant2Email.address) for an inline contact, or use [`recipient.transport`](https://python.inttegro.dev/v12.0.0/inttegro/chime.html#SavedCustomerRecipientInput.transport) plus [`recipient.customer_id`](https://python.inttegro.dev/v12.0.0/inttegro/chime.html#SavedCustomerRecipientInput.customer_id) for a saved customer. Never combine [`recipient.transport`](https://python.inttegro.dev/v12.0.0/inttegro/chime.html#SavedCustomerRecipientInput.transport) with inline contact details.

**Send notification — POST /chimes/send**

```python
import os

import inttegro
from inttegro import InttegroClient

client = InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])

result = client.chimes.send(inttegro.chime.SendRequest(
  recipient=inttegro.chime.InlineRecipientInputVariant1(
    type=inttegro.chime.RecipientType.PHONE,
    phone=inttegro.chime.InlineRecipientInputVariant1Phone(
      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://pages.inttegro.com/invoices/track/OR-7821",
  sender_id="YourStore",
  purpose="notification",
  request_meta=inttegro.chime.SendRequestRequestMeta(
    idempotency_key="notify_order_OR-7821_confirmed",
  ),
  custom_data=inttegro.CustomData({
    "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.

### Attaching metadata

Use [`custom_data`](https://python.inttegro.dev/v12.0.0/inttegro/chime.html#Chime) 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 [Lookup chime](https://studio.inttegro.com/machine/python/api/chimes.md#lookup-chime) with the Chime ID. The response includes transmission status, delivery timestamps, and all metadata from creation.

**Check delivery — POST /chimes/lookup**

```python
import os

from inttegro import InttegroClient

client = InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])

result = client.chimes.lookup("WkPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYU")
```

Status values indicate message progress: `'initialized'` means a transmission exists but has not been sent, `'sent'` means the message was handed off but delivery is not confirmed, `'delivered'` means delivery was confirmed, and `'failed'` means the transmission could not complete.

## 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 [Schedule chime](https://studio.inttegro.com/machine/python/api/chimes.md#schedule-chime) with the message, [`send_after`](https://python.inttegro.dev/v12.0.0/inttegro/schedule.html#ChimeRequest.send_after), and recipient objects. Inline recipients use `recipients[].type` plus a matching phone or email object; saved customers use `recipients[].transport` plus `recipients[].customer_id`.

**Schedule notification — POST /chimes/schedule**

```python
import os
from datetime import datetime

import inttegro
from inttegro import InttegroClient

client = InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])

result = client.chimes.schedule(inttegro.schedule.ChimeRequest(
  recipients=[
    inttegro.chime.InlineRecipientInputVariant1(
      type="phone",
      phone=inttegro.chime.InlineRecipientInputVariant1Phone(
        number="+233544998605",
      ),
    ),
    inttegro.chime.InlineRecipientInputVariant1(
      type="phone",
      phone=inttegro.chime.InlineRecipientInputVariant1Phone(
        number="+233501234567",
      ),
    ),
  ],
  full_message="Reminder: Your subscription renews in 3 days on Dec 18. Update payment details at https://pages.inttegro.com/invoices/billing or contact support.",
  send_after=datetime.fromisoformat("2030-12-15T09:00:00Z".replace("Z", "+00:00")),
  sender_id="YourBrand",
  purpose="reminder",
))
```

Scheduled Chimes deliver at or shortly after the specified time. Inttegro resolves every saved customer and validates every inline phone number or email address before accepting the schedule. A malformed or unresolved recipient rejects the request; later transmission failures remain isolated to the affected recipient.

## 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 so customers know where they are 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.

## Next steps

- **[Chime API Reference](https://studio.inttegro.com/machine/python/api/chimes.md)** — Complete endpoint documentation and response formats
- **[Product: Chime](https://studio.inttegro.com/machine/python/products/chimes.md)** — Deep dive into Chime features and use cases
- **[OTP API](https://studio.inttegro.com/machine/python/api/otps.md)** — Send verification codes for authentication flows
- **[Orders](https://studio.inttegro.com/machine/python/api/orders.md)** — Trigger notifications from order events