---
title: codespar_notify
description: Messaging meta-tool. WhatsApp BR via Z-API; SMS / email USD via Twilio + SendGrid; WhatsApp INTL via Twilio.
---

import { Callout } from "fumadocs-ui/components/callout";

# codespar_notify

<Callout title="Meta-tool" type="info">
**Sell-side.** Your agent is the merchant: it collects from, invoices, ships to, or verifies a counterparty.

`codespar_notify` is the unified messaging interface for transactional notifications — order confirmations, shipping updates, payment receipts, KYC nudges. The agent picks `recipient` and `message`; CodeSpar picks the channel and rail.
</Callout>

There is no typed wrapper yet — call via `session.execute()` (or `session.send()` if you do not need the delivery receipt).

## Rails

| Rail | Currency | Country | Provider | Notes |
|---|---|---|---|---|
| WhatsApp | BRL | BR | Z-API | Default for BR — `path_secret` auth, phone_id-scoped |
| WhatsApp | INTL | INTL | Twilio | Form-encoded body. Different from Z-API's JSON shape |
| SMS | USD | INTL | Twilio | Account SID + Auth Token |
| Email | USD | INTL | SendGrid | API key |

The router prefers Z-API for BR WhatsApp because Z-API has lower latency and supports template-free chat for verified business numbers; Twilio is the global fallback.

## Direct execute

```ts
const result = await session.execute("codespar_notify", {
  recipient: "+5511999998888",
  message: "Olá, Maria! Seu pedido #1234 foi enviado. Rastreio: BR123456789.",
  channel: "whatsapp",
});

console.log(result.id, result.status); // "queued" or "sent"
```

For email:

```ts
const result = await session.execute("codespar_notify", {
  recipient: "maria@example.com",
  subject: "Order #1234 confirmation",
  message: "Hi Maria, your order has shipped.",
  channel: "email",
});
```

## Args shape

| Field | Type | Required | Description |
|---|---|---|---|
| `recipient` | `string` | Yes | Phone in E.164 format (`+5511...`) for WhatsApp/SMS, email address for email |
| `message` | `string` | Yes | Body content. WhatsApp BR honors plaintext; email + SMS truncate at provider limits |
| `channel` | `string` | No | `whatsapp`, `sms`, `email`. Inferred from `recipient` shape if omitted |
| `subject` | `string` | No | Email only |
| `template_id` | `string` | No | Provider-side template id (Z-API HSM, Twilio template, SendGrid dynamic-template) |
| `variables` | `object` | No | Template substitutions when `template_id` is set |

## Result shape

```ts
type NotifyResult = {
  id: string;                    // provider message id
  status: "queued" | "sent" | "delivered" | "failed";
  channel: string;
  delivered_at?: string;         // ISO 8601, set on terminal "delivered"
};
```

For `session.execute()` you get the synchronous send/queue result. Delivery confirmation lands later as a webhook — wire a [trigger](/docs/concepts/triggers) on `notify.delivered` if you need it.

## Operator setup

Each rail wants its own credentials in `/dashboard/auth-configs`:

- **Z-API** — `path_secret` auth_type. Operator uploads a phone-id (path-embedded) plus a companion header token. Connection scoped to a single Z-API instance.
- **Twilio** — Account SID + Auth Token (basic-auth shape). Same credentials drive SMS, voice, and Twilio WhatsApp.
- **SendGrid** — API key (`api_key` auth_type) with `mail.send` scope.

For Z-API the path_secret pattern is documented in [path_secret auth](/docs/concepts/authentication#path-secret-auth) — the phone_id is the path component and the companion header is `Client-Token`.

## See also

- [Tools & meta-tools](/docs/concepts/tools) — full meta-tool list
- [Pix Payment Agent cookbook](/docs/cookbooks/pix-payment-agent) — `codespar_notify` paired with `codespar_pay`
- [Webhook Listener cookbook](/docs/cookbooks/webhook-listener) — fire-and-forget on settlement
- [Triggers](/docs/concepts/triggers) — subscribe to `notify.delivered` events