codespar_notify

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

Rails

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

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:

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

Result shape

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 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 — the phone_id is the path component and the companion header is Client-Token.

See also

• Tools & meta-tools — full meta-tool list
• Pix Payment Agent cookbook — codespar_notify paired with codespar_pay
• Webhook Listener cookbook — fire-and-forget on settlement
• Triggers — subscribe to notify.delivered events