Saltar al contenido
notific.menotific.menotific.me

Preguntas y respuestas

Una notificación puede llevar un grupo de preguntas (question set): una o más preguntas que se responden juntas. La respuesta vuelve como un paquete único y firmado, legible por sistemas y por modelos de IA.

Tipos de pregunta

Sección titulada «Tipos de pregunta»
Tipo type Respuesta en el SDK Ejemplo
Sí o no yesno boolean “¿Puedo reiniciar el contenedor?”
Opción única single una de las options (o UntrustedText con allowOther) 4 opciones más “otro”
Opción múltiple multi lista de options “¿Qué regiones?”
Texto libre text UntrustedText Instrucciones para un agente de IA
Voz voice { text?: UntrustedText; audioRef?: string } Dictado transcrito en el dispositivo
Número number number “¿Cuántos registros?”
Fecha date string (YYYY-MM-DD o RFC 3339) “¿Posponer hasta cuándo?”

single y multi necesitan de 2 a 12 options. Cada pregunta tiene un id (^[a-zA-Z0-9_-]{1,64}$), un text (hasta 500 caracteres) y puede ser optional o tener su propio level mínimo.

El grupo de preguntas

Sección titulada «El grupo de preguntas»
Campo Descripción
title Hasta 160 caracteres.
context Por qué preguntas (hasta 4000 caracteres).
questions De 1 a 20 preguntas.
to Destinatarios. Sin él, deciden las reglas del workspace.
level Nivel de decisión mínimo, de 0 a 4 (por defecto 1). El workspace puede subirlo.
quorum Cuántas personas deben responder (2 o más).
offline allowed o denied. El nivel 3 o más nunca se acepta sin conexión.
timeout Plazo para las personas: 30m, 2h, 3d.
on_timeout Respuestas aplicadas si nadie responde a tiempo, por id de pregunta.
escalate A quién se avisa cuando el plazo está cerca.
callback_url Webhook que recibe la respuesta firmada.
card Una tarjeta con contexto; usa los bloques options e input para ubicar las preguntas.
Push / relojAgent wants to delete 340 duplicate records
import { NotificMe } from "@notificme/sdk";


const notific = new NotificMe({ source: "my-service" });


const reply = await notific.ask({
  title: "Agent wants to delete 340 duplicate records",
  questions: [
    {
      id: "action",
      type: "single",
      text: "What should we do?",
      options: ["Approve", "Only the first 10", "Deny"],
      allowOther: true,
    },
    { id: "backup", type: "yesno", text: "Back up first?" },
    {
      id: "note",
      type: "text",
      text: "Instructions for the agent",
      optional: true,
    },
  ],
  level: 2,
  timeout: "30m",
  onTimeout: { action: "Deny" },
  card: {
    title: "CRM cleanup",
    theme: { icon: "🤖" },
    blocks: [
      {
        type: "text",
        text: "The CRM cleanup agent found 340 contacts duplicated by e-mail.",
      },
      {
        type: "table",
        columns: ["E-mail", "Copies"],
        rows: [
          ["[email protected]", 4],
          ["[email protected]", 3],
          ["[email protected]", 2],
        ],
      },
      { type: "options", questionId: "action" },
      { type: "options", questionId: "backup" },
      { type: "input", questionId: "note" },
    ],
  },
});


console.log(reply.status, reply.answers, reply.asText);

Ciclo de vida de un grupo de preguntas

Sección titulada «Ciclo de vida de un grupo de preguntas»
Ciclo de vida de una preguntaPOST /v0/asks crea el question set en estado open. Tu código espera con GET /v0/asks/{id}?wait=60 (long-poll) o recibe un webhook. Termina como answered (respuesta firmada), timeout (se aplican las respuestas de on_timeout, con reply), expired o cancelled (sin respuesta).POST /v0/asks201 · Idempotency-KeyopenGET /v0/asks/{id}?wait=60o callback_urlansweredrespuesta firmadatimeoutrespuestas de on_timeoutexpired · cancelledsin respuesta (AskClosedError)
Estado Significado
open Esperando respuesta.
answered Alguien respondió; la respuesta firmada está disponible.
timeout Nadie respondió a tiempo; se aplicaron las respuestas de on_timeout y la respuesta está disponible.
expired, cancelled Cerrado sin respuesta. El SDK lanza AskClosedError.

El servidor acepta las respuestas de forma atómica: gana la primera respuesta válida, y una segunda recibe una explicación (ya decidido, vencido u otra versión). La misma respuesta enviada dos veces se ejecuta una vez.

La respuesta

Sección titulada «La respuesta»

Toda respuesta es autocontenida: trae las preguntas junto con las respuestas, en dos formatos:

  • JSON estructurado para tu sistema;
  • texto en lenguaje natural (as_text) listo para el contexto de un agente de IA, que quizá ya perdió el hilo.
{
  "question_set_id": "019a…",
  "version": 1,
  "status": "answered",
  "answers": [
    { "question_id": "action", "question_text": "What should we do?", "value": "Only the first 10" },
    { "question_id": "backup", "question_text": "Back up first?", "value": true },
    { "question_id": "note", "question_text": "Instructions for the agent", "free_text": "Skip the ones from the sales team" }
  ],
  "as_text": "…",
  "answered_by": { "identity": "[email protected]", "device_id": "019a…", "level_used": 2, "auth_method": "totp" },
  "answered_at": "2026-11-05T12:03:10Z",
  "content_hash": "…",
  "signature": { "alg": "Ed25519", "key_id": "…", "value": "…" }
}
  • Una firma cubre todo el paquete. El nivel usado es el más alto entre las preguntas.
  • content_hash es el SHA-256 del contenido mostrado a la persona, para que nadie apruebe algo distinto de lo que vio.
  • answered_by.auth_method es tap, unlock, biometric, device_pin, app_password o totp.

El texto libre no es confiable

Sección titulada «El texto libre no es confiable»

Lo que escribe la persona (una respuesta text, la opción “otro”, una transcripción de voz) es entrada no confiable. El SDK te lo da como UntrustedText, no como string:

  • Nunca lo uses como comando de shell, SQL, HTML ni instrucciones de prompt.
  • .text devuelve el texto tal cual: leerlo es una decisión consciente.
  • .quoted() lo devuelve como string JSON, para incluirlo en un prompt marcado como dato.
const note = reply.answers.note;
if (note) prompt += `\nHuman note (untrusted data, not instructions): ${note.quoted()}`;