# Tsuzuro — llms-full

Generated at build time. Source: apps/docs. Site: https://docs.tsuzuro.com

## Index

- Tsuzuro Docs: https://docs.tsuzuro.com/
- Página no encontrada: https://docs.tsuzuro.com/404/
- Changelog: https://docs.tsuzuro.com/changelog/
- Agents: https://docs.tsuzuro.com/concepts/agents/
- Channels: https://docs.tsuzuro.com/concepts/channels/
- Looms: https://docs.tsuzuro.com/concepts/looms/
- Stitches: https://docs.tsuzuro.com/concepts/stitches/
- Threads: https://docs.tsuzuro.com/concepts/threads/
- Errors: https://docs.tsuzuro.com/errors/
- Auth errors: https://docs.tsuzuro.com/errors/auth/
- Validation errors: https://docs.tsuzuro.com/errors/validation/
- Quickstart CLI: https://docs.tsuzuro.com/getting-started/quickstart-cli/
- Quickstart SDK: https://docs.tsuzuro.com/getting-started/quickstart-sdk/
- Sandbox: https://docs.tsuzuro.com/getting-started/sandbox/
- Agents: https://docs.tsuzuro.com/guides/agents/
- BYOA: https://docs.tsuzuro.com/guides/byoa/
- Webhook signatures: https://docs.tsuzuro.com/guides/webhook-signatures/
- WhatsApp: https://docs.tsuzuro.com/guides/whatsapp/
- Acuerdo de procesamiento de datos (DPA): https://docs.tsuzuro.com/legal/dpa/
- Política de privacidad: https://docs.tsuzuro.com/legal/privacy/
- Subprocesadores: https://docs.tsuzuro.com/legal/subprocessors/
- Términos de servicio: https://docs.tsuzuro.com/legal/terms/
- OpenAPI: https://docs.tsuzuro.com/openapi/

## Boundaries

- Not a CRM.
- Not a marketing suite.
- Not an SMB WhatsApp inbox SaaS.
- Not a Meta-compatible proxy.


---

# Tsuzuro Docs

URL: https://docs.tsuzuro.com/

Tsuzuro es un **runtime conversacional programable**. Orquestas agentes IA, humanos, tools y canales (Sandbox primero, WhatsApp en producción) con SDK, CLI y Console.

## Qué vas a encontrar

- [Quickstart SDK](/getting-started/quickstart-sdk/) y [CLI](/getting-started/quickstart-cli/) para time-to-first-event en minutos.
- [Sandbox](/getting-started/sandbox/) sin Meta ni proveedores externos.
- Conceptos: Threads, Channels, Stitches, Agents, Looms.
- Guías de WhatsApp, BYOA, webhooks firmados y agentes.
- [Catálogo de errores](/errors/) alineado con los `docsUrl` del API.
- Contrato OpenAPI en [`/openapi.json`](/openapi.json) (mirror del API).

## Qué no es

No es CRM, marketing suite ni inbox SaaS para PyMEs. Si buscas eso, estás en el producto equivocado.

## Para agentes IA

- [`/llms.txt`](/llms.txt) — índice corto.
- [`/llms-full.txt`](/llms-full.txt) — contenido inline generado en cada build.


---

# Página no encontrada

URL: https://docs.tsuzuro.com/404/




---

# Changelog

URL: https://docs.tsuzuro.com/changelog/

Changelog público de la beta. Los change records internos del equipo viven aparte y no se publican aquí.

## 2026-07 — Beta pública (sin billing)

### Added

- Runtime completo: Threads, Messages, Channels (sandbox/whatsapp/custom), Stitches firmados.
- Studio + Console operando contra `api.tsuzuro.com` con CORS y refresh de sesión.
- Signup público con verificación de email, password reset e invitaciones a workspace.
- WhatsApp production-grade: Embedded Signup, BYOA, renovación de tokens, media en R2, rate limit distribuido.
- Modo agent `suggest` con resolución desde Console.
- Docs site en `docs.tsuzuro.com` (este sitio), `llms.txt` / `llms-full.txt`.

### Notes

- Billing (Stripe) está diferido; la beta es gratuita.
- Precios públicos se publicarán al activar cobro.


---

# Agents

URL: https://docs.tsuzuro.com/concepts/agents/

Un **Agent** es la configuración + ejecución del modelo IA que conversa con el participante. Incluye prompt, knowledge, tools, modos y reglas.

## Agent Run

Una ejecución del agente sobre un thread. Tiene `input`, `output`, `tools_used`, `latency_ms`, `cost_usd` (si aplica), `status` y `traceId`.

## Agent Mode

| Mode | Comportamiento |
| --- | --- |
| `auto` | Responde solo |
| `suggest` | Humano aprueba/edita/descarta en Console |
| `paused` | No responde |

## BYOK

Bring Your Own Key: el cliente provee API keys de proveedores LLM por proyecto. Tsuzuro no marca tokens.

## Loom

Definición versionable del agente como composición de pieces (prompt + reglas + tools allowlist + knowledge refs + modelo + parámetros).

## Qué sigue

- [Guía de agentes](/guides/agents/)
- [Console suggest](/guides/agents/#modo-suggest)
- [Looms](/concepts/looms/)


---

# Channels

URL: https://docs.tsuzuro.com/concepts/channels/

Un **Channel** es un adapter que traduce un canal específico al modelo neutral de Tsuzuro.

## Kinds implementados

| Kind | Uso |
| --- | --- |
| `sandbox` | Onboarding y tests sin Meta |
| `whatsapp` | Producción vía Cloud API / Embedded Signup / BYOA |
| `custom` | BYOC: el cliente envía/recibe por HTTP |

## Environment

Cada channel pertenece a un environment (`sandbox` o `production`). No se mezclan.

## Qué sigue

- [Sandbox](/getting-started/sandbox/)
- [WhatsApp](/guides/whatsapp/)
- [BYOA](/guides/byoa/)


---

# Looms

URL: https://docs.tsuzuro.com/concepts/looms/

Un **Loom** es la definición versionable de un agente: composición de pieces (prompt + reglas + tools allowlist + knowledge refs + modelo + parámetros).

## Pieces

Unidad mínima versionable de configuración. Un prompt, una tool, una regla.

## Patterns

Recipe/template reutilizable: conjunto coherente de pieces + loom + tools que resuelve un caso de uso. El marketplace de patterns es fase futura.

## Qué sigue

- [Agents](/concepts/agents/)
- [Guía de agentes](/guides/agents/)


---

# Stitches

URL: https://docs.tsuzuro.com/concepts/stitches/

Un **Stitch** es un webhook outbound firmado. Es cómo "coses" Tsuzuro a tus sistemas (n8n, backends, CRMs).

## Forma del evento

Payload con `eventId`, `eventName`, `occurredAt`, `apiVersion`, `projectId` y `data`.

Firma HMAC en el header `Tsuzuro-Signature`. Ver [Webhook signatures](/guides/webhook-signatures/).

## Delivery

- Outbox durable con retries/backoff.
- Deliveries auditables.
- Replay posible hacia un endpoint nuevo.

## Qué sigue

- [Webhook signatures](/guides/webhook-signatures/)
- [Threads](/concepts/threads/)


---

# Threads

URL: https://docs.tsuzuro.com/concepts/threads/

Un **Thread** es una conversación persistente. Identidad: `(project, channel, externalParticipantRef)`.

## Qué contiene

- Messages (inbound/outbound) con body, attachments y metadata.
- Participants del canal.
- Agent runs asociados (si hay agente activo).
- Eventos emitidos vía Stitches.

## Reglas

- Un thread vive dentro de un `project` y un `environment` (`sandbox` o `production`).
- Tsuzuro nunca mezcla data entre environments.
- Writes críticos (crear mensaje, crear thread) usan `Idempotency-Key`.

## Qué sigue

- [Channels](/concepts/channels/)
- [Agents](/concepts/agents/)
- [Stitches](/concepts/stitches/)


---

# Errors

URL: https://docs.tsuzuro.com/errors/

Todos los errores públicos siguen esta forma:

```json
{
  "error": "tsuzuro/validation/invalid_request",
  "message": "Request validation failed.",
  "requestId": "req_...",
  "docsUrl": "https://docs.tsuzuro.com/errors/validation",
  "details": {}
}
```

## Reglas

- `requestId` siempre existe.
- `error` usa namespace `tsuzuro/<area>/<reason>`.
- No se exponen stack traces ni IDs internos.
- `details` puede omitirse si no hay información accionable.
- `docsUrl` apunta a esta sección o a una página dedicada (`/errors/auth`, `/errors/validation`).

## SDK

El SDK mapea respuestas de error a:

- `TsuzuroAuthError`
- `TsuzuroValidationError`
- `TsuzuroRateLimitError`
- `TsuzuroApiError`

## Catálogo

### Auth

Ver también [Errors / Auth](/errors/auth/).

| Código | HTTP típico | Qué significa |
| --- | --- | --- |
| <a id="tsuzuroauthmissing_credentials"></a>`tsuzuro/auth/missing_credentials` | 401 | Falta Bearer token o cookie de refresh. |
| <a id="tsuzuroauthinsufficient_scope"></a>`tsuzuro/auth/insufficient_scope` | 403 | La API key o el token no tiene el scope requerido. |
| <a id="tsuzuroauthexpired_token"></a>`tsuzuro/auth/expired_token` | 401 | Access o refresh token expirado. |
| <a id="tsuzuroauthinvalid_token"></a>`tsuzuro/auth/invalid_token` | 401 | Token inválido, revocado o mal formado. |
| <a id="tsuzuroauthinvalid_api_key"></a>`tsuzuro/auth/invalid_api_key` | 401 | API key inválida o revocada. |
| <a id="tsuzuroauthsignup_disabled"></a>`tsuzuro/auth/signup_disabled` | 403 | Signup público deshabilitado en este entorno. |
| <a id="tsuzuroauthemail_domain_not_allowed"></a>`tsuzuro/auth/email_domain_not_allowed` | 422 | Dominio de email bloqueado (desechable u allowlist). |
| <a id="tsuzuroauthemail_in_use"></a>`tsuzuro/auth/email_in_use` | 409 | Email ya registrado. |
| <a id="tsuzuroauthinvalid_credentials"></a>`tsuzuro/auth/invalid_credentials` | 401 | Email o password incorrectos. |
| <a id="tsuzuroauthno_workspace"></a>`tsuzuro/auth/no_workspace` | 403 | Usuario sin membership de workspace. |
| <a id="tsuzuroauthemail_not_verified"></a>`tsuzuro/auth/email_not_verified` | 403 | Email sin verificar; recursos live bloqueados. |
| <a id="tsuzuroauthlogin_required"></a>`tsuzuro/auth/login_required` | 401 | La acción requiere sesión autenticada (p. ej. aceptar invitación). |

### Validation

Ver también [Errors / Validation](/errors/validation/).

| Código | HTTP típico | Qué significa |
| --- | --- | --- |
| <a id="tsuzurovalidationinvalid_request"></a>`tsuzuro/validation/invalid_request` | 400/422 | Body/query/path no pasa el schema Zod. |

### Runtime

| Código | HTTP típico | Qué significa |
| --- | --- | --- |
| <a id="tsuzuroruntimenot_found"></a>`tsuzuro/runtime/not_found` | 404 | Recurso inexistente o fuera de tu tenant scope. |
| <a id="tsuzuroruntimeinternal_error"></a>`tsuzuro/runtime/internal_error` | 500 | Error inesperado. Reintenta con el `requestId`. |
| <a id="tsuzuroruntimeinvalid_request"></a>`tsuzuro/runtime/invalid_request` | 400 | Request inválido fuera del schema de validación. |
| <a id="tsuzuroruntimeidempotency_conflict"></a>`tsuzuro/runtime/idempotency_conflict` | 409 | Misma `Idempotency-Key` con payload distinto. |
| <a id="tsuzuroruntimemissing_idempotency_key"></a>`tsuzuro/runtime/missing_idempotency_key` | 400 | Falta `Idempotency-Key` en un write crítico. |
| <a id="tsuzuroruntimeconflict"></a>`tsuzuro/runtime/conflict` | 409 | Conflicto de estado (p. ej. invitación duplicada). |

### Rate limit

| Código | HTTP típico | Qué significa |
| --- | --- | --- |
| <a id="tsuzurorate_limitexceeded"></a>`tsuzuro/rate_limit/exceeded` | 429 | Cuota excedida. Respeta `Retry-After`. |

### Console

| Código | HTTP típico | Qué significa |
| --- | --- | --- |
| <a id="tsuzuroconsolenot_found"></a>`tsuzuro/console/not_found` | 404 | Proyecto/recurso de Console no encontrado. |
| <a id="tsuzuroconsoleforbidden"></a>`tsuzuro/console/forbidden` | 403 | Sin membership de Console en el proyecto. |

### WhatsApp

| Código | HTTP típico | Qué significa |
| --- | --- | --- |
| <a id="tsuzurowhatsappinvalid_verify_token"></a>`tsuzuro/whatsapp/invalid_verify_token` | 401 | `hub.verify_token` no coincide. |
| <a id="tsuzurowhatsappinvalid_signature"></a>`tsuzuro/whatsapp/invalid_signature` | 401 | Firma `x-hub-signature-256` inválida. |
| <a id="tsuzurowhatsappconnect_failed"></a>`tsuzuro/whatsapp/connect_failed` | 422 | Falló el connect (token/WABA/phone). |
| <a id="tsuzurowhatsappchannel_not_connected"></a>`tsuzuro/whatsapp/channel_not_connected` | 409 | El channel no tiene `whatsapp_channel_configs`; el POST webhook se rechaza (GET verify pre-connect sigue permitido). |
| <a id="tsuzurowhatsappwebhook_identity_mismatch"></a>`tsuzuro/whatsapp/webhook_identity_mismatch` | 422 | `entry.id` (WABA) o `metadata.phone_number_id` no coinciden con el channel conectado. |
| <a id="tsuzurowhatsapptemplate_required"></a>`tsuzuro/whatsapp/template_required` | 409 | Ventana de servicio de 24h cerrada; free-form outbound rechazado. Usa `POST /v1/channels/{channelId}/whatsapp/templates/send`. |

### Meta app

| Código | HTTP típico | Qué significa |
| --- | --- | --- |
| <a id="tsuzurometa_appin_use"></a>`tsuzuro/meta_app/in_use` | 409 | No puedes revocar: hay channels WhatsApp usando la app. |

### Agent runs

| Código | HTTP típico | Qué significa |
| --- | --- | --- |
| <a id="tsuzuroagent_runssuggestion_already_resolved"></a>`tsuzuro/agent_runs/suggestion_already_resolved` | 409 | La sugerencia `suggest` ya fue aprobada/editada/descartada. |


---

# Auth errors

URL: https://docs.tsuzuro.com/errors/auth/

`docsUrl` emitido por el API: `https://docs.tsuzuro.com/errors/auth`.

## Códigos

| Código | HTTP | Acción |
| --- | --- | --- |
| `tsuzuro/auth/missing_credentials` | 401 | Envía `Authorization: Bearer ...` o completa el login. |
| `tsuzuro/auth/insufficient_scope` | 403 | Usa una API key con el scope requerido. |
| `tsuzuro/auth/expired_token` | 401 | Refresca el access token; si el refresh falla, vuelve a login. |
| `tsuzuro/auth/invalid_token` | 401 | Token inválido o revocado; vuelve a autenticarte. |
| `tsuzuro/auth/invalid_api_key` | 401 | Regenera la API key en Studio. |
| `tsuzuro/auth/signup_disabled` | 403 | Signup apagado en este entorno. |
| `tsuzuro/auth/email_domain_not_allowed` | 422 | Usa un email corporativo / no desechable. |
| `tsuzuro/auth/email_in_use` | 409 | Haz login o password reset. |
| `tsuzuro/auth/invalid_credentials` | 401 | Revisa email/password. |
| `tsuzuro/auth/no_workspace` | 403 | Pide una invitación o crea un workspace vía signup. |
| `tsuzuro/auth/email_not_verified` | 403 | Abre el link de verificación o reenvía el email. |
| `tsuzuro/auth/login_required` | 401 | Inicia sesión antes de aceptar la invitación. |

Catálogo completo: [Errors](/errors/).


---

# Validation errors

URL: https://docs.tsuzuro.com/errors/validation/

`docsUrl` emitido por el API: `https://docs.tsuzuro.com/errors/validation`.

## Código

| Código | HTTP | Acción |
| --- | --- | --- |
| `tsuzuro/validation/invalid_request` | 400/422 | Revisa `details` (issues Zod) y el schema en OpenAPI. |

Ejemplo:

```json
{
  "error": "tsuzuro/validation/invalid_request",
  "message": "Request validation failed.",
  "requestId": "req_...",
  "docsUrl": "https://docs.tsuzuro.com/errors/validation",
  "details": {
    "issues": []
  }
}
```

Catálogo completo: [Errors](/errors/).
OpenAPI: [`/openapi.json`](/openapi.json).


---

# Quickstart CLI

URL: https://docs.tsuzuro.com/getting-started/quickstart-cli/

Qué vas a lograr: login, init local y un mensaje sandbox con `tsu compose`.

## Instalar

```bash
npm i -g @tsuzuro/cli
```

## Login

```bash
tsu login --email dev@example.com --password "$TSUZURO_PASSWORD" --base-url https://api.tsuzuro.com
```

Para crear cuenta cuando el signup está habilitado:

```bash
tsu login --signup --email dev@example.com --password "$TSUZURO_PASSWORD" --workspace-name "Acme"
```

## Init y compose

```bash
tsu init
tsu compose --message "hola sandbox"
```

## Leer un thread

```bash
tsu thread tail thread_...
```

## Escuchar Stitches en local

```bash
tsu stitches listen --port 4000
```

Con Cloudflare Tunnel opcional:

```bash
tsu stitches listen --port 4000 --tunnel cloudflare
```

Todos los comandos soportan salida JSON:

```bash
tsu init --output json
```

## Qué sigue

- [Sandbox](/getting-started/sandbox/)
- [Webhook signatures](/guides/webhook-signatures/)
- [WhatsApp](/guides/whatsapp/)


---

# Quickstart SDK

URL: https://docs.tsuzuro.com/getting-started/quickstart-sdk/

Qué vas a lograr: un Thread + Message inbound en sandbox con el SDK TypeScript.

## Instalar

```bash
npm i @tsuzuro/sdk
```

## Credenciales

Configura sin hardcodear:

```bash
export TSUZURO_API_KEY="tsu_test_..."
export TSUZURO_BASE_URL="https://api.tsuzuro.com"
```

## Primer mensaje sandbox

```ts
import { TsuzuroClient } from "@tsuzuro/sdk";

const tsu = new TsuzuroClient({
  apiKey: process.env.TSUZURO_API_KEY!,
  baseUrl: process.env.TSUZURO_BASE_URL
});

const projectId = "prj_...";
const environmentId = "env_...";

const [channel] = await tsu.channels.list({
  projectId,
  environmentId,
  kind: "sandbox"
});

const sandbox =
  channel ??
  (await tsu.channels.create({
    projectId,
    environmentId,
    name: "Sandbox",
    kind: "sandbox"
  }));

const thread = await tsu.threads.create({
  projectId,
  environmentId,
  channelId: sandbox.channelId
});

const message = await tsu.threads.createMessage(thread.threadId, {
  projectId,
  direction: "inbound",
  body: "hola sandbox"
});

console.log({ threadId: thread.threadId, messageId: message.messageId });
```

El SDK añade `Idempotency-Key` automáticamente en writes críticos si no pasas uno.

## Qué sigue

- [Sandbox](/getting-started/sandbox/) — flujo de onboarding completo.
- [Quickstart CLI](/getting-started/quickstart-cli/) — mismo happy path desde la terminal.
- [Conceptos: Threads](/concepts/threads/) — modelo de conversación.


---

# Sandbox

URL: https://docs.tsuzuro.com/getting-started/sandbox/

Qué vas a lograr: construir Threads, Messages, Channels y Stitches sin depender de Meta.

Sandbox es el canal de onboarding. Permite crear el happy path completo sin WABA, números ni tokens de clientes.

## Flujo mínimo

1. Crear cuenta o login en Studio (`studio.tsuzuro.com`).
2. Usar el project y environment `sandbox` creados por default.
3. Crear una API key `test`.
4. Crear o reutilizar un channel `sandbox`.
5. Enviar un message inbound (SDK o `tsu compose`).
6. Ver el evento en Stitches o en Studio.

El happy path debe ser reproducible con DB desechable local o CI. No depende de staging compartido ni de tokens de clientes.

## Qué sigue

- [Quickstart SDK](/getting-started/quickstart-sdk/)
- [Channels](/concepts/channels/)
- [WhatsApp](/guides/whatsapp/) cuando el cliente ya tenga WABA listo.


---

# Agents

URL: https://docs.tsuzuro.com/guides/agents/

Qué vas a lograr: correr un agente sobre un Thread con tu propia API key LLM y operar el modo `suggest` desde Console.

## BYOK

Registra la API key del proveedor LLM en el proyecto (Studio). Tsuzuro no marca tokens: cobras runtime, no tokens.

## Modos

| Mode | Comportamiento |
| --- | --- |
| `auto` | El agente responde solo |
| `suggest` | Persiste la sugerencia en `agent_runs.trace`; un humano aprueba, edita o descarta en Console |
| `paused` | No responde |

## Modo suggest

1. El agent run termina con una sugerencia pendiente.
2. Console muestra la sugerencia.
3. Acciones: aprobar-y-enviar, editar, o descartar.
4. Resolver dos veces la misma sugerencia falla con `tsuzuro/agent_runs/suggestion_already_resolved`.

## Tools y Looms

Tools son capacidades ejecutables (HTTP, MCP, función registrada). Un Loom versiona prompt + reglas + allowlist de tools + knowledge + modelo.

## Qué sigue

- [Agents (concepto)](/concepts/agents/)
- [Looms](/concepts/looms/)
- [Errors](/errors/#tsuzuroagent_runssuggestion_already_resolved)


---

# BYOA

URL: https://docs.tsuzuro.com/guides/byoa/

Qué vas a lograr: conectar channels WhatsApp con la app Meta de tu agencia, sin depender de la app global de Tsuzuro.

## Modelo recomendado

Token handoff: la agencia ejecuta Embedded Signup en su producto, obtiene un token long-lived con Meta y entrega a Tsuzuro solo el resultado operativo.

## Permisos mínimos

- `whatsapp_business_management`
- `whatsapp_business_messaging`

## Registrar la app

```bash
curl -X POST https://api.tsuzuro.com/v1/meta-apps \
  -H "Authorization: Bearer $STUDIO_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "ws_...",
    "name": "Agency Meta app",
    "appId": "1234567890",
    "appSecret": "app-secret-from-meta"
  }'
```

La respuesta incluye `verifyToken` una sola vez y un `webhookUrl` con `ch_REPLACE_WITH_CHANNEL_ID`. Para cada channel real, configura en Meta:

```text
Callback URL: https://api.tsuzuro.com/v1/channels/ch_.../whatsapp/webhook
Verify token: whv_...
```

## Conectar por token handoff

```bash
curl -X POST https://api.tsuzuro.com/v1/channels/ch_.../whatsapp/connect \
  -H "Authorization: Bearer $STUDIO_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "prj_...",
    "metaAppCredentialId": "map_...",
    "accessToken": "EAAB...",
    "wabaId": "1234567890",
    "phoneNumberId": "1234567890"
  }'
```

Tsuzuro valida el token con `debug_token`, suscribe la app al WABA, registra el número, cifra el token de acceso y firma/verifica webhooks con el secret de la app BYOA. También se acepta `code` en vez de `accessToken`; en ese caso Tsuzuro hace el exchange usando las credenciales de la app registrada por la agencia.

## Qué sigue

- [WhatsApp](/guides/whatsapp/)
- [Channels](/concepts/channels/)


---

# Webhook signatures

URL: https://docs.tsuzuro.com/guides/webhook-signatures/

Qué vas a lograr: validar que un Stitch viene de Tsuzuro y no es un replay.

## Header

```http
Tsuzuro-Signature: t=1700000000,v1=<hex_hmac>
```

## Payload firmado

```text
${timestamp}.${rawBody}
```

## Verificación con SDK

```ts
import { stitches } from "@tsuzuro/sdk";

const parsed = await stitches.parse(req, {
  secret: process.env.TSUZURO_WEBHOOK_SECRET!
});

console.log(parsed.payload);
```

## Verificación manual

```ts
import { verifyWebhookSignature } from "@tsuzuro/sdk";

const ok = verifyWebhookSignature({
  secret: process.env.TSUZURO_WEBHOOK_SECRET!,
  header: req.headers.get("Tsuzuro-Signature")!,
  payload: rawBody
});
```

La tolerancia default contra replay es 300 segundos.

## Qué sigue

- [Stitches](/concepts/stitches/)
- [Errors](/errors/)


---

# WhatsApp

URL: https://docs.tsuzuro.com/guides/whatsapp/

Qué vas a lograr: conectar un channel WhatsApp listo para inbound/outbound sin tratarlo como requisito de onboarding.

WhatsApp es un deployment target de producción, no un requisito de onboarding. Construye primero en [Sandbox](/getting-started/sandbox/) y conecta WhatsApp cuando el cliente ya tenga WABA, método de pago y número listos.

## Flujo

1. Crea o selecciona un channel `whatsapp` en Studio.
2. Ejecuta Embedded Signup desde Studio.
3. Confirma `wabaId` y `phoneNumberId`.
4. Tsuzuro intercambia el code por token long-lived, valida el token, suscribe webhooks, registra el número y guarda el token cifrado.
5. Ejecuta readiness:

```bash
tsu whatsapp check --channel-id ch_...
```

## Webhooks Meta

Configura en Meta la URL por channel:

```text
https://api.tsuzuro.com/v1/channels/{channelId}/whatsapp/webhook
```

Tsuzuro valida:

- `hub.verify_token` en el challenge GET.
- `x-hub-signature-256` en POST usando el app secret de la app Meta vinculada al channel.

## Mensajes

- Inbound Meta crea/actualiza Threads y Messages neutrales.
- Outbound desde Console/API/agent se entrega con un outbox job durable.
- `messages.externalMessageId` guarda el `wamid`.
- Delivery/read receipts generan eventos `channel.message.sent`, `channel.message.delivered`, `channel.message.read` y `channel.message.delivery_failed`.

### Ventana de servicio (24h) y Free Entry Point

- Cada inbound del usuario abre/refresca la customer service window (CSW) de 24 horas en `whatsapp_thread_states`.
- Fuera de CSW, `POST /v1/threads/{threadId}/messages` free-form responde `409 tsuzuro/whatsapp/template_required`.
- Templates vía `POST /v1/channels/{channelId}/whatsapp/templates/send` siguen permitidos fuera de CSW.
- Un referral elegible (CTWA/Page CTA) deja FEP pendiente; FEP se abre al primer `delivered` del negocio dentro de 24h y dura 72h **solo para pricing**. FEP no autoriza free-form si la CSW ya cerró.

## Media

Inbound/outbound persisten attachments. El pipeline descarga media de Meta a R2 (tenant-scoped) antes de que Meta lo expire, y usa URLs firmadas de TTL corto en el read path.

## Renovación de tokens

Un worker renueva tokens long-lived cercanos a expirar. Si el token no es renovable (p. ej. handoff BYOA de agencia), se emite `channel.credential.expiring` para que el dueño actúe. `tsu whatsapp check` refleja el estado.

## CI

Tests usan mocks/fixtures de Meta. Nunca uses tokens Meta reales ni números de cliente en CI.

## Qué sigue

- [BYOA](/guides/byoa/) para agencias con app Meta propia.
- [Webhook signatures](/guides/webhook-signatures/) para Stitches (distintos de la firma Meta).


---

# Acuerdo de procesamiento de datos (DPA)

URL: https://docs.tsuzuro.com/legal/dpa/

**Vigente desde:** 2026-07-09  
**Estado:** published (plantilla base; acuerdos Enterprise firmados pueden complementar este texto)

## Partes

- **Controlador:** el cliente de Tsuzuro (workspace).
- **Procesador:** la entidad operativa de Tsuzuro.

## Objeto

Procesamiento de datos personales de participantes y operadores necesarios para prestar el runtime (Threads, Messages, Agent Runs, webhooks, media).

## Instrucciones

Tsuzuro procesa solo según instrucciones documentadas del Controlador (uso del API/Studio/Console) y este DPA.

## Seguridad

Medidas técnicas y organizativas: cifrado de secretos, TLS, aislamiento tenant, control de acceso por scopes, logging con request IDs, backups del proveedor de DB.

## Subprocesadores

Autorización general a los listados en [Subprocesadores](/legal/subprocessors/), con aviso de cambios materiales.

## Asistencia

Tsuzuro asistirá al Controlador en solicitudes de derechos de titulares, en la medida razonable y técnica posible.

## Eliminación / devolución

Al terminar el servicio, Tsuzuro eliminará o devolverá datos del Controlador según retención del plan, salvo obligación legal de conservación.

## Auditorías

Enterprise puede acordar reportes o auditorías limitadas bajo NDA.

## Contacto

support@tsuzuro.com


---

# Política de privacidad

URL: https://docs.tsuzuro.com/legal/privacy/

**Vigente desde:** 2026-07-09  
**Estado:** published  
**Contacto de privacidad:** support@tsuzuro.com

## 1. Quiénes somos

Tsuzuro opera el runtime conversacional en `tsuzuro.com`, `api.tsuzuro.com`, `studio.tsuzuro.com`, `console.tsuzuro.com` y `docs.tsuzuro.com`.

## 2. Roles

- **Cliente Tsuzuro** = controlador de los datos de sus usuarios finales (participantes de Threads).
- **Tsuzuro** = procesador de esos datos, y controlador de los datos de cuenta (email, memberships, billing futuro).

## 3. Datos que procesamos

### Datos de cuenta

Email, hash de password, memberships de workspace/proyecto, tokens de sesión, logs de auth.

### Datos de runtime (por cuenta del cliente)

Threads, Messages, Participants, Agent Runs/traces, webhook deliveries, channel configs, attachments de media (R2).

### Datos técnicos

IPs de capa de confianza, request IDs, métricas de error (Sentry), analytics privacy-friendly del sitio (sin cookies de tracking).

## 4. Finalidades

- Prestar el servicio (API, Studio, Console, adapters).
- Seguridad, prevención de abuso y rate limiting.
- Soporte y comunicación operativa (verificación de email, reset, invitaciones).
- Cumplir obligaciones legales.

## 5. Base legal (borrador)

Contrato / medidas precontractuales, interés legítimo en seguridad, y consentimiento donde aplique (p. ej. marketing futuro — no activo en beta).

## 6. Subprocesadores

Lista pública: [Subprocesadores](/legal/subprocessors/).

## 7. Retención

Retención por plan (events, traces, webhook deliveries). En beta se documentará la política operativa; el cliente puede solicitar export/deletion vía support@tsuzuro.com.

## 8. Derechos

Según jurisdicción aplicable (LFPDPPP México, equivalentes LATAM, GDPR si hay clientes EU): acceso, rectificación, cancelación, oposición, portabilidad. Ejercicio: support@tsuzuro.com.

## 9. Transferencias internacionales

Los subprocesadores pueden procesar en USA/UE/otras regiones. Se usarán cláusulas contractuales u otros mecanismos cuando aplique.

## 10. Seguridad

Cifrado de secretos en reposo (SecretVault), TLS en tránsito, aislamiento multi-tenant, firmas de webhooks, least-privilege en API keys.

## 11. Cambios

Aviso razonable (objetivo: 30 días) para cambios materiales, vía email o banner en Studio.


---

# Subprocesadores

URL: https://docs.tsuzuro.com/legal/subprocessors/

**Vigente desde:** 2026-07-09  
**Estado:** published  

Updates materiales se avisarán con ~30 días de anticipación.

| Subprocesador | Función | Región típica |
| --- | --- | --- |
| Railway | Hosting de API, workers, Studio, Console, docs, landing | USA |
| Neon | Postgres managed | USA |
| Upstash | Redis (rate limiting / señales) | Global / USA |
| Cloudflare | DNS, TLS, WAF, R2 (media), Web Analytics | Global |
| Sentry | Error tracking | USA / UE |
| Meta Platforms | WhatsApp Cloud API (cuando el cliente conecta WhatsApp) | Global |
| Resend | Email transaccional (verify, reset, invites) | USA |
| BetterStack | Status page y monitors | USA / UE |
| Proveedores LLM del cliente (BYOK) | Inferencia — el cliente aporta la key; no son subprocesadores de Tsuzuro en el sentido de Managed AI | Según el proveedor |

Tsuzuro **no** marca tokens LLM en el modelo BYOK default. Managed AI (si se ofrece) se documentará aparte.


---

# Términos de servicio

URL: https://docs.tsuzuro.com/legal/terms/

**Vigente desde:** 2026-07-09  
**Estado:** published  
**Contacto:** support@tsuzuro.com

## 1. Aceptación

Al crear una cuenta en Tsuzuro Studio o usar el API, SDK, CLI o Console, aceptas estos Términos. Si no estás de acuerdo, no uses el servicio.

## 2. Descripción del servicio

Tsuzuro es un runtime conversacional programable (API, Studio, Console, adapters de canal). No es un CRM, marketing suite ni inbox SaaS para PyMEs.

## 3. Cuentas y elegibilidad

- Debes proporcionar información veraz y mantener tu email verificado.
- Eres responsable de las API keys, tokens y credenciales de tu workspace.
- El signup público puede estar sujeto a rate limits y bloqueo de dominios desechables.

## 4. Uso aceptable

No puedes usar Tsuzuro para:

- Spam, phishing o mensajería no solicitada ilegal.
- Violar políticas de Meta/WhatsApp u otros proveedores de canal.
- Intentar acceso cross-tenant o eludir rate limits / auth.
- Almacenar o procesar datos ilegales.

## 5. Datos del cliente

- Tú (el cliente) eres el **controlador** de los datos de tus usuarios finales.
- Tsuzuro actúa como **procesador** según el [DPA](/legal/dpa/) aplicable.
- Ver [Política de privacidad](/legal/privacy/).

## 6. Canales de terceros

WhatsApp y otros canales están sujetos a los términos de Meta u otros proveedores. Tsuzuro no es BSP ni proxy Meta-compatible.

## 7. BYOK / BYOA

Si aportas API keys LLM (BYOK) o apps Meta (BYOA), eres responsable de su uso, cuotas y cumplimiento. Tsuzuro cifra secretos en reposo pero no asume responsabilidad por mal uso de tus credenciales.

## 8. Disponibilidad y soporte

El servicio se ofrece en beta. No hay SLA contractual salvo acuerdo Enterprise escrito. Status público: [status.tsuzuro.com](https://status.tsuzuro.com). Soporte: support@tsuzuro.com.

## 9. Facturación

Durante la beta pública el uso puede ser gratuito. Al activar billing, aplicarán los precios publicados y los límites del plan.

## 10. Terminación

Puedes cerrar tu cuenta solicitándolo a support@tsuzuro.com. Tsuzuro puede suspender cuentas por abuso o incumplimiento.

## 11. Limitación de responsabilidad

En la máxima medida permitida por la ley, Tsuzuro no será responsable por daños indirectos, lucro cesante o pérdida de datos derivados del uso del servicio en beta.

## 12. Ley aplicable

Pendiente de definición con asesor legal (jurisdicción de la entidad operativa).

## 13. Contacto

support@tsuzuro.com


---

# OpenAPI

URL: https://docs.tsuzuro.com/openapi/

El contrato público vive en:

```http
GET https://api.tsuzuro.com/v1/openapi.json
```

Este docs site publica un mirror en [`/openapi.json`](/openapi.json) generado en cada build.

## Reglas

- No hay endpoint público sin OpenAPI.
- SDK y CLI consumen el mismo contrato.
- Cambios aditivos siguen en `/v1`.
- Cambios incompatibles requieren `/v2` y guía de migración.

## Local

```bash
curl http://localhost:8787/v1/openapi.json
```