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.

Use MCP for customer SMS and delivery checks

An authenticated AI agent can send a customer SMS after confirmation, then list or look up Chime records to help support delivery questions.

MCP tools: send_customer_sms, list_messages or get_message

Confirmed MCP actions require explicit form confirmation before Inttegro changes state.

Note

Don't use Chimes for verification codes. If you need to authenticate or verify users with one-time passwords, use the OTP API 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 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—initialized, sent, delivered, or failed—so you can determine whether a transmission has started and whether delivery was confirmed.

For email recipients, include a top-level email object with subject, text, and from.address, and omit full_message. Inttegro validates the sender, rejects header injection, scans links and HTML, and only sends sanitized content that passes the safety policy.

{
  "recipient": {
    "type": "email",
    "email": {
      "address": "[email protected]"
    }
  },
  "email": {
    "subject": "Your receipt is ready",
    "text": "Your receipt is ready. View it at https://yourstore.example/receipts/or_7821.",
    "from": {
      "address": "[email protected]"
    }
  }
}

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 with one of two recipient shapes: use type plus the matching phone.number or email.address for an inline contact, or use transport plus customer_id for a saved customer. Never combine transport with inline contact details.

Send notification

POST/chimes/send

curl https://api.inttegro.com/chimes/send \
  -H "Authorization: Bearer $INTTEGRO_API_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://pages.inttegro.com/invoices/track/OR-7821",
    "sender_id": "YourStore",
    "purpose": "notification",
    "request_meta": {
      "idempotency_key": "notify_order_OR-7821_confirmed"
    },
    "custom_data": {
      "order_id": "OR-7821",
      "event": "order_confirmed",
      "customer_id": "cu_gloria_k"
    }
  }'

SDK versionv8.2.0

import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.chimes.send({
  recipient: {
    type: Inttegro.ChimeRecipientTypes.Phone,
    phone: {
      number: "+233544998605",
    },
    name: "Gloria Kesewaa",
  },
  fullMessage: "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",
  senderId: "YourStore",
  purpose: "notification",
  requestMeta: {
    idempotencyKey: "notify_order_OR-7821_confirmed",
  },
  customData: {
    order_id: "OR-7821",
    event: "order_confirmed",
    customer_id: "cu_gloria_k",
  },
})

SDK versionv4.4.0

package main

import (
  "context"
  "log"
  "os"

  inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)

func main() {
  ctx := context.Background()
  client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))

  params := inttegro.SendChimeParams{
    Recipient: inttegro.ChimeRecipient{
      Type: inttegro.ChimeRecipientTypePhone,
      Phone: &struct { Number string `json:"number"` }{
        Number: "+233544998605",
      },
      Name: "Gloria Kesewaa",
    },
    FullMessage: "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",
    Purpose: "notification",
    CustomData: map[string]string{
      "order_id": "OR-7821",
      "event": "order_confirmed",
      "customer_id": "cu_gloria_k",
    },
  }
  result, err := client.Chimes.Send(ctx, params)
  if err != nil {
    log.Fatal(err)
  }
  _ = result
}

SDK versionv6.2.0

import os
import inttegro

client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.chimes.send(inttegro.chimes.SendRequest(
  recipient=inttegro.chimes.PhoneRecipient(
    type=inttegro.ChimeRecipientType.PHONE,
    phone=inttegro.chimes.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://pages.inttegro.com/invoices/track/OR-7821",
  sender_id="YourStore",
  purpose="notification",
  request_meta=inttegro.chimes.SendRequestMeta(
    idempotency_key="notify_order_OR-7821_confirmed",
  ),
  custom_data={
    "order_id": "OR-7821",
    "event": "order_confirmed",
    "customer_id": "cu_gloria_k",
  },
))

SDK versionv5.3.0

<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->chimes->send([
  'recipient' => [
    'type' => \Inttegro\ChimeRecipientType::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://pages.inttegro.com/invoices/track/OR-7821',
  'sender_id' => 'YourStore',
  'purpose' => 'notification',
  'request_meta' => [
    'idempotency_key' => 'notify_order_OR-7821_confirmed',
  ],
  'custom_data' => [
    'order_id' => 'OR-7821',
    'event' => 'order_confirmed',
    'customer_id' => 'cu_gloria_k',
  ],
]);

SDK versionv4.3.0

require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.chimes.send(
  recipient: {
    type: Inttegro::ChimeRecipientType::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://pages.inttegro.com/invoices/track/OR-7821",
  sender_id: "YourStore",
  purpose: "notification",
  request_meta: {
    idempotency_key: "notify_order_OR-7821_confirmed",
  },
  custom_data: {
    order_id: "OR-7821",
    event: "order_confirmed",
    customer_id: "cu_gloria_k",
  }
)

SDK versionv5.2.0

import com.inttegro.Client;
import com.inttegro.chimes.SendChimeParams;
import com.inttegro.chimes.ChimeRecipient;
import com.inttegro.chimes.ChimeRecipientType;
import com.inttegro.chimes.Phone;
import java.util.Map;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = SendChimeParams.builder()
      .recipient(ChimeRecipient.builder()
          .type(ChimeRecipientType.PHONE)
          .phone(Phone.builder()
              .number("+233544998605")
              .build())
          .name("Gloria Kesewaa")
          .build())
      .fullMessage("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")
      .purpose("notification")
      .customData(Map.<String, String>ofEntries(
          Map.entry("order_id", "OR-7821"),
          Map.entry("event", "order_confirmed"),
          Map.entry("customer_id", "cu_gloria_k")
        ))
      .build();
    var result = client.chimes().send(params);
  }
}

SDK versionv6.2.0

using Inttegro;

using var inttegro = new InttegroClient(
    Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.Chimes.SendAsync(new {
  recipient = new {
    type = Inttegro.ChimeRecipientType.Phone,
    phone = new {
      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 = new {
    idempotency_key = "notify_order_OR-7821_confirmed",
  },
  custom_data = new {
    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 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 with the Chime ID. The response includes transmission status, delivery timestamps, and all metadata from creation.

Check delivery

POST/chimes/lookup

curl https://api.inttegro.com/chimes/lookup \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chime_id": "WkPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYU"
  }'

SDK versionv8.2.0

import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.chimes.lookup({
  chimeId: "WkPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYU",
})

SDK versionv4.4.0

package main

import (
  "context"
  "log"
  "os"

  inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)

func main() {
  ctx := context.Background()
  client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))

  result, err := client.Chimes.Lookup(ctx, "WkPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYU")
  if err != nil {
    log.Fatal(err)
  }
  _ = result
}

SDK versionv6.2.0

import os
import inttegro

client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.chimes.lookup("WkPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYU")

SDK versionv5.3.0

<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->chimes->lookup("WkPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYU");

SDK versionv4.3.0

require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.chimes.lookup(chime_id: "WkPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYU")

SDK versionv5.2.0

import com.inttegro.Client;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var result = client.chimes().lookup("WkPvqTrqGsopu07wfC7ttoWqmfwt48ZW7BGvYU");
  }
}

SDK versionv6.2.0

using Inttegro;

using var inttegro = new InttegroClient(
    Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.Chimes.LookupAsync("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 with the message, send_after, and recipient objects. Inline recipients use type plus a matching phone or email object; saved customers use transport plus customer_id.

Schedule notification

POST/chimes/schedule

curl https://api.inttegro.com/chimes/schedule \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      { "type": "phone", "phone": { "number": "+233544998605" } },
      { "type": "phone", "phone": { "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": "2030-12-15T09:00:00Z",
    "sender_id": "YourBrand",
    "purpose": "reminder"
  }'

SDK versionv8.2.0

import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.chimes.schedule({
  recipients: [
    {
      type: "phone",
      phone: {
        number: "+233544998605",
      },
    },
    {
      type: "phone",
      phone: {
        number: "+233501234567",
      },
    },
  ],
  fullMessage: "Reminder: Your subscription renews in 3 days on Dec 18. Update payment details at https://pages.inttegro.com/invoices/billing or contact support.",
  sendAfter: "2030-12-15T09:00:00Z",
  senderId: "YourBrand",
  purpose: "reminder",
})

SDK versionv4.4.0

package main

import (
  "context"
  "log"
  "os"

  inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)

func main() {
  ctx := context.Background()
  client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))

  params := inttegro.ScheduleChimeParams{
    Recipients: []string{
      "",
      "",
    },
    FullMessage: "Reminder: Your subscription renews in 3 days on Dec 18. Update payment details at https://pages.inttegro.com/invoices/billing or contact support.",
    SendAfter: "2030-12-15T09:00:00Z",
    SenderID: "YourBrand",
    Purpose: "reminder",
  }
  result, err := client.Chimes.Schedule(ctx, params)
  if err != nil {
    log.Fatal(err)
  }
  _ = result
}

SDK versionv6.2.0

import os
import inttegro

client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.chimes.schedule(inttegro.chimes.ScheduleRequest(
  recipients=[
    inttegro.chimes.PhoneRecipient(
      type="phone",
      phone=inttegro.chimes.Phone(
        number="+233544998605",
      ),
    ),
    inttegro.chimes.PhoneRecipient(
      type="phone",
      phone=inttegro.chimes.Phone(
        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="2030-12-15T09:00:00Z",
  sender_id="YourBrand",
  purpose="reminder",
))

SDK versionv5.3.0

<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->chimes->schedule([
  'recipients' => [
    [
      'type' => 'phone',
      'phone' => [
        'number' => '+233544998605',
      ],
    ],
    [
      'type' => 'phone',
      'phone' => [
        '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' => '2030-12-15T09:00:00Z',
  'sender_id' => 'YourBrand',
  'purpose' => 'reminder',
]);

SDK versionv4.3.0

require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.chimes.schedule(
  recipients: [
    {
      type: "phone",
      phone: {
        number: "+233544998605",
      },
    },
    {
      type: "phone",
      phone: {
        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: "2030-12-15T09:00:00Z",
  sender_id: "YourBrand",
  purpose: "reminder"
)

SDK versionv5.2.0

import com.inttegro.Client;
import com.inttegro.chimes.ScheduleChimeParams;
import java.util.List;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = ScheduleChimeParams.builder()
      .recipients(List.of(
          "",
          ""
        ))
      .fullMessage("Reminder: Your subscription renews in 3 days on Dec 18. Update payment details at https://pages.inttegro.com/invoices/billing or contact support.")
      .sendAfter("2030-12-15T09:00:00Z")
      .senderId("YourBrand")
      .purpose("reminder")
      .build();
    var result = client.chimes().schedule(params);
  }
}

SDK versionv6.2.0

using Inttegro;

using var inttegro = new InttegroClient(
    Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.Chimes.ScheduleAsync(new {
  recipients = new[] {
    new {
      type = "phone",
      phone = new {
        number = "+233544998605",
      },
    },
    new {
      type = "phone",
      phone = new {
        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 = "2030-12-15T09:00:00Z",
  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—checkout.inttegro.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.

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

How it works

Step 1: send a notification immediately

Send notification

Attaching metadata​

Step 2: check delivery status

Check delivery

Schedule notifications for future delivery

Schedule notification

Crafting effective notifications

Front-load critical information​

Include actionable links​

Keep SMS under 160 characters​

Next steps

Attaching metadata

Front-load critical information

Include actionable links

Keep SMS under 160 characters