API reference

import { createSendo } from "@quami/sendo";
import { supabaseAdapter } from "@quami/sendo/adapters/supabase";
import { createClient } from "@supabase/supabase-js";
import { z } from "zod";

function requireEnv(name: string): string {
  const value = process.env[name];
  if (value === undefined || value.trim() === "") {
    throw new Error(`[sendo] Missing environment variable ${name}. Add it to .env.local.`);
  }
  return value;
}

// Service-role client: server only, never import this file from client components.
const supabaseAdmin = createClient(
  requireEnv("NEXT_PUBLIC_SUPABASE_URL"),
  requireEnv("SUPABASE_SERVICE_ROLE_KEY"),
  { auth: { persistSession: false, autoRefreshToken: false } },
);

export const sendo = createSendo({
  adapter: supabaseAdapter(supabaseAdmin, {
    storageBucket: process.env.SENDO_STORAGE_BUCKET ?? "sendo-media",
  }),
  appSecret: requireEnv("SENDO_META_APP_SECRET"),
  verifyToken: requireEnv("SENDO_VERIFY_TOKEN"),
  // sendo_accounts.token_ref holds the NAME of the env var with the token (e.g. SENDO_TOKEN_MAIN).
  resolveToken: (account) => process.env[account.tokenRef],
  // findPatientIdByPhone / listAdminIds stand for your own queries.
  // Your entity id for this phone number (patient, resident, user), or null.
  linkContact: async ({ phone, account }) => findPatientIdByPhone(phone, account.tenantId),
  // Who gets a handed-off conversation. Exactly one id auto-assigns it.
  resolveHandoffTargets: async ({ account }) => listAdminIds(account.tenantId),
  agentDefaults: { historyLimit: 20, maxStepsPerTurn: 5, maxMessagesPerMinutePerContact: 10 },
  eventRetentionDays: 30,
  logger: console,
});

const unsubscribe = sendo.on("message", async ({ message, contact, conversation, reply }) => {
  if (message.type === "text" && message.text?.trim().toLowerCase() === "menu") {
    await reply.buttons({
      body: `Hola ${contact.profileName ?? ""}, ¿qué necesitas?`,
      buttons: [
        { id: "cita", title: "Agendar cita" },
        { id: "humano", title: "Hablar con alguien" },
      ],
    });
  }
  if (message.media?.downloadStatus === "done") {
    console.log("stored at", message.media.storagePath, "in", conversation.id);
  }
});

sendo.on("status", ({ message, status, error }) => {
  if (status === "failed") console.warn("send failed", message.id, error?.code, error?.message);
});

sendo.on("handoff", async ({ conversation, assignees, reason }) => {
  await notifyStaff(assignees, `Conversación ${conversation.id}: ${reason}`);
});

sendo.on("conversation.status", ({ conversation, from, to, by }) => {
  console.log(conversation.id, from, "→", to, "by", by);
});

sendo.on("account.error", ({ account, error }) => {
  if (error.isInvalidToken) console.error(`Token ${account.tokenRef} expired or was revoked`);
});

sendo.on("event.unrouted", ({ phoneNumberId }) => {
  console.warn("Webhook for an unknown phone_number_id", phoneNumberId);
});

unsubscribe(); // stop listening

sendo.send.text(to, body, { account?, tenant?, previewUrl?, replyTo? }): Promise<Message>
sendo.send.media(to, { type, url? | file? | id?, mimeType?, caption?, filename? }, { account?, tenant?, replyTo? })
sendo.send.buttons(to, { body, buttons: { id, title }[] /* ≤ 3 */, header?, footer? }, { account?, tenant?, replyTo? })
sendo.send.list(to, { body, button, sections, header?, footer? }, { account?, tenant?, replyTo? })
sendo.send.template(to, name, { language, variables?, headerMedia?, buttons?, account?, tenant?, replyTo? })
sendo.send.markRead(messageId): Promise<void>

// Numbers are normalized to E.164: "+502 5555-1234" and "50255551234" both work.
const message = await sendo.send.text("+502 5555-1234", "Hola, tu cita está confirmada.", {
  previewUrl: false,
});
console.log(message.id, message.metaMessageId, message.status); // "sent"

await sendo.send.media("50255551234", { type: "image", url: "https://example.com/receta.png" });
await sendo.send.media("50255551234", { type: "document", file, filename: "factura.pdf" });

await sendo.send.buttons("50255551234", {
  body: "¿Confirmas tu cita de mañana a las 10:00?",
  buttons: [
    { id: "confirmar", title: "Confirmar" },
    { id: "reprogramar", title: "Reprogramar" },
  ],
  footer: "Clínica Central",
});

await sendo.send.list("50255551234", {
  body: "Elige un servicio",
  button: "Ver servicios",
  sections: [
    {
      title: "Consultas",
      rows: [
        { id: "general", title: "Medicina general" },
        { id: "pediatria", title: "Pediatría", description: "Lunes a viernes" },
      ],
    },
  ],
});

// Templates work outside the 24-hour window. Positional {{1}} or named {{nombre}} variables.
await sendo.send.template("50255551234", "recordatorio_cita", {
  language: "es",
  variables: ["Ana", "mañana 10:00"],
});

await sendo.send.markRead("wamid.HBgLNTAy..."); // sendo id or Meta id of an inbound message

// Pull approved templates from Meta into sendo_templates (run after creating or editing one).
await sendo.templates.sync(); // every active account, or { account }
const templates = await sendo.templates.list({ status: "APPROVED" });
console.log(templates.map((t) => `${t.name}/${t.language} (${t.variableCount} vars)`));

const conversation = await sendo.conversations.get(conversationId); // null if unknown
const { open, expiresAt } = await sendo.conversations.windowStatus(conversationId);

await sendo.conversations.handoff(conversationId, { reason: "Pide hablar con una persona" });
await sendo.conversations.assign(conversationId, userId, { by: userId }); // also sets "human"
await sendo.conversations.returnToAgent(conversationId, { by: userId });
await sendo.conversations.close(conversationId, { by: userId });
// No agent turns on this conversation; on resume it doesn't answer what arrived meanwhile.
await sendo.conversations.pauseAgent(conversationId, true, { by: userId });

const event = await sendo.events.get(eventId); // raw payload + status
if (event?.status === "failed" || event?.status === "unrouted") {
  const after = await sendo.events.reprocess(eventId); // idempotent: messages are deduped
  console.log(after.status, after.error);
}

const deleted = await sendo.maintenance.prune(); // eventRetentionDays (default 30)
await sendo.maintenance.prune({ olderThanDays: 7 });

// Any runtime with Web Request/Response (Hono, Supabase Edge Functions, Workers...).
const worker = {
  fetch(request: Request, _env: unknown, ctx: { waitUntil(p: Promise<unknown>): void }) {
    // GET: verify challenge. POST: signature check, store event, 200, then process in
    // the background through waitUntil (without it the work runs as a detached promise).
    return sendo.handleWebhook(request, { waitUntil: (p) => ctx.waitUntil(p) });
  },
};

export default worker;

// app/api/sendo/webhook/route.ts (installed by @sendo/webhook)
import { toNextHandlers } from "@quami/sendo/next";
import { sendo } from "@/lib/sendo";

export const { GET, POST } = toNextHandlers(sendo); // POST uses next/server `after()`
export const runtime = "nodejs";
export const maxDuration = 60;

const agendarCita = agentTool({
  description: "Agenda una cita para el paciente vinculado a esta conversación",
  input: z.object({ fecha: z.iso.date(), hora: z.string().regex(/^\d{2}:\d{2}$/) }),
  // `input` is already validated (and typed) by the zod schema.
  async run({ input, contact, account }) {
    // Authorize inside the tool: only act on the entity linked to THIS contact.
    if (contact.appRef === null) {
      return { error: "Paciente no identificado. Pide su número de DPI." };
    }
    return bookAppointment({
      tenantId: account.tenantId,
      patientId: contact.appRef,
      date: input.fecha,
      time: input.hora,
    });
  },
});

const handle = sendo.agent({
  name: "recepcion",
  // Only numbers of tenants with the feature on (or a list of account / phone number ids).
  accounts: (account) => account.tenantId !== null,
  model: "openai/gpt-5-mini",
  instructions: async ({ contact, account }) =>
    `Eres la recepción de ${await clinicName(account.tenantId)}. ` +
    `Atiende a ${contact.profileName ?? "el paciente"} en español, en mensajes breves.`,
  tools: { agendar_cita: agendarCita },
  handoff: {
    when: "pide hablar con una persona, tiene una urgencia o está molesto",
    to: "recepcion",
    message: "Te comunico con una persona del equipo.", // null sends nothing
  },
  historyLimit: 20,
  maxStepsPerTurn: 5,
  maxMessagesPerMinutePerContact: 10,
  fallbackMessage: null,
  vision: true,
  timezone: "America/Guatemala",
});

console.log(handle.name, HANDOFF_TOOL_NAME); // "recepcion", "transferir_a_humano"
handle.remove(); // unregister

import { supabaseAdapter } from "@quami/sendo/adapters/supabase";
import { createClient } from "@supabase/supabase-js";

// The SERVICE ROLE client (bypasses RLS). Server only.
const supabaseAdmin = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL ?? "",
  process.env.SUPABASE_SERVICE_ROLE_KEY ?? "",
  { auth: { persistSession: false, autoRefreshToken: false } },
);

export const adapter = supabaseAdapter(supabaseAdmin, {
  storageBucket: "sendo-media", // private bucket
  signedUrlTtlSec: 300,
});

import { createSendo } from "@quami/sendo";
import { memoryAdapter } from "@quami/sendo/adapters/memory";

// In-memory storage for unit tests and quick experiments. Nothing is persisted.
const adapter = memoryAdapter({ now: () => new Date("2026-10-06T12:00:00Z") });

const sendo = createSendo({
  adapter,
  appSecret: "test-secret",
  verifyToken: "test-verify",
  resolveToken: () => "test-token",
});

await adapter.accounts.insert({
  phoneNumberId: "100000000000001",
  wabaId: "200000000000001",
  displayPhone: "+1 555 000 1111",
  tokenRef: "SENDO_TOKEN_MAIN",
});
adapter.reset(); // clears every table between tests

// my-adapter.contract.test.ts (run with Vitest)
import { runAdapterContract } from "@quami/sendo/adapters/contract";
import type { SendoAdapter } from "@quami/sendo";

declare function createMyAdapter(): Promise<SendoAdapter>;
declare function truncateTables(): Promise<void>;
declare const databaseReachable: boolean;

runAdapterContract("my-adapter", () => createMyAdapter(), {
  skip: databaseReachable ? false : "database unreachable",
  afterEach: truncateTables,
});

interface MediaStore {
  put(path: string, bytes: Uint8Array, mimeType: string): Promise<void>;
  get(path: string): Promise<Uint8Array | null>; // null when missing
  signedUrl(path: string, ttlSeconds: number): Promise<string>;
  delete(paths: string[]): Promise<void>; // missing paths are ignored
  exists?(): Promise<boolean>; // doctor's bucket check
}

import { S3Client } from "@aws-sdk/client-s3";
import { s3Storage } from "@quami/sendo/storage/s3";

export const media = s3Storage({
  client: new S3Client({
    region: "auto",
    endpoint: process.env.S3_ENDPOINT, // e.g. https://<account>.r2.cloudflarestorage.com; omit for AWS
    credentials: {
      accessKeyId: process.env.S3_ACCESS_KEY_ID!,
      secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
    },
  }),
  bucket: process.env.S3_BUCKET ?? "sendo-media",
});

export const sendo = createSendo({ adapter, media /* , ... */ });

import { GRAPH_API_VERSION, createSendo, metaDirect } from "@quami/sendo";
import { memoryAdapter } from "@quami/sendo/adapters/memory";

// Same as the appSecret / verifyToken / resolveToken shorthand, plus transport options.
const transport = metaDirect({
  appSecret: process.env.SENDO_META_APP_SECRET ?? "",
  verifyToken: process.env.SENDO_VERIFY_TOKEN ?? "",
  resolveToken: (account) => process.env[account.tokenRef],
  version: GRAPH_API_VERSION, // pinned Graph API version, e.g. "v26.0"
});

export const sendo = createSendo({ adapter: memoryAdapter(), transport });

import type { Account, FetchedMedia, MessagePayload, Transport } from "@quami/sendo";

// The interface metaDirect implements. Pass any object implementing it as `transport`.
export class GatewayTransport implements Transport {
  readonly kind = "gateway";

  async send(account: Account, payload: MessagePayload): Promise<{ metaMessageId: string }> {
    return gateway("send", { phoneNumberId: account.phoneNumberId, payload });
  }

  async fetchMedia(account: Account, mediaId: string): Promise<FetchedMedia> {
    return gateway("media", { phoneNumberId: account.phoneNumberId, mediaId });
  }

  // Optional: uploadMedia?(account, input), markRead?(account, metaMessageId),
  // handleWebhook?(request) → Response, subscribe?(handler) → unsubscribe.
}

try {
  return await sendo.send.text(phone, "¿Seguimos con tu cita?");
} catch (error) {
  if (error instanceof WindowClosedError) {
    // Free-form text is blocked 24 h after the contact's last message: use a template.
    return sendo.send.template(phone, "recordatorio_cita", {
      language: "es",
      variables: ["Ana"],
    });
  }
  if (error instanceof TemplateNotFoundError) console.error(error.templateName, error.language);
  if (error instanceof AmbiguousAccountError)
    console.error("Pass { account }:", error.candidates);
  if (error instanceof MetaApiError) {
    console.error(error.status, error.metaCode, error.subcode, error.fbtraceId);
  }
  if (isSendoError(error)) {
    // Stable string codes, safe to branch on and to log: error.toJSON() has no cause/stack.
    console.error(error.code, error.toJSON());
  }
  throw error;
}

normalizePhone("+502 5555-1234"); // "+50255551234"
normalizePhone("5555 1234", { defaultCountry: "GT" }); // "+50255551234"
isValidPhone("123"); // false (normalizePhone throws InvalidPhoneError)

windowStatus(lastInboundAt); // { open, expiresAt } — 24 h after the last inbound message

// Lower-level webhook helpers (sendo.handleWebhook already does this for you).
if (verifySignature(rawBody, signature, process.env.SENDO_META_APP_SECRET ?? "")) {
  for (const change of parseWebhook(JSON.parse(rawBody))) {
    console.log(change.phoneNumberId, change.messages.length, change.statuses.length);
  }
}

console.log(GRAPH_API_VERSION, SENDO_SCHEMA_VERSION, META_MEDIA_LIMITS.image); // "v26.0", 3 (schema version), bytes