Tu automatización. Una conversación.

01Antes de empezar

Crea una cuenta y una conversación en la app de pruebas internas de Pushyou a la que te invitaron. El acceso web requiere aprobar un QR en esa app. La guía de conexión permite elegir la conversación y comprobar la entrega.

Crea una conexión por programa en Ajustes → Conexiones. Autoriza solo las conversaciones y operaciones necesarias. Las claves se muestran una sola vez. El acceso a salas seleccionadas no permite crear otras; se requiere acceso a todas y conversations:write.

02Autenticación

Ejecuta estos comandos en Bash o zsh, en tu ordenador o servidor. Guarda la clave en la configuración de secretos de tu entorno. No la incluyas en código del navegador, URL ni vistas publicadas. Los tokens OAuth de MCP no autentican solicitudes REST.

export PUSHYOU_API_URL='https://asia-northeast3-pushyou-prod.cloudfunctions.net/pushyouApi'
export PUSHYOU_MEDIA_URL='https://asia-northeast3-pushyou-prod.cloudfunctions.net/pushyouMedia'

printf 'Pushyou API key: ' >&2
IFS= read -r -s PUSHYOU_API_KEY
printf '\n' >&2
export PUSHYOU_API_KEY

curl --fail-with-body --silent --show-error \
  -X GET "$PUSHYOU_API_URL/v1/me" \
  -H "Authorization: Bearer $PUSHYOU_API_KEY"

03Envía tu primer mensaje

Elegir una conversación existente

Comprueba id, permissions y conversation_ids en la respuesta de la cuenta. Si conversation_ids es null, el acceso incluye todas las conversaciones. Lista las salas permitidas y sustituye YOUR_CONVERSATION_ID por un ID real. Esta consulta requiere conversations:read.

curl --fail-with-body --silent --show-error \
  -X GET "$PUSHYOU_API_URL/v1/conversations?limit=20" \
  -H "Authorization: Bearer $PUSHYOU_API_KEY"

export PUSHYOU_CONVERSATION_ID='YOUR_CONVERSATION_ID'

curl --fail-with-body --silent --show-error \
  -X POST "$PUSHYOU_API_URL/v1/conversations/$PUSHYOU_CONVERSATION_ID/messages" \
  -H "Authorization: Bearer $PUSHYOU_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"id":"docs-message-01","text":"Pushyou connection verified.","notify":true}'

{
  "conversation_id": "YOUR_CONVERSATION_ID",
  "message_id": "docs-message-01",
  "duplicate": false
}

Usa un ID estable para cada mensaje lógico. Repetir el mismo ID y contenido devuelve HTTP 200 con duplicate: true. Un contenido distinto con el mismo ID devuelve 409. Usa un ID nuevo para un mensaje nuevo.

Campos del mensaje

Las listas de conversaciones, mensajes e historial usan limit (1–100, 50 por defecto) y before=next_cursor. Conserva los filtros y detente cuando next_cursor sea null. Los eventos usan un cursor numérico after en orden ascendente. Las consultas no marcan los mensajes como leídos en la app.

04Respuestas y ejecución

Responde en la app y consulta los eventos. Tras procesar realmente una respuesta o acción ordinaria, guarda el resultado, envía su ACK y conserva next_cursor en almacenamiento persistente. El ACK no elimina el evento ni concede ejecución exclusiva. Usa un único programa de respuesta por sala o coordina los consumidores.

curl --fail-with-body --silent --show-error \
  -X GET "$PUSHYOU_API_URL/v1/conversations/$PUSHYOU_CONVERSATION_ID/events?after=0" \
  -H "Authorization: Bearer $PUSHYOU_API_KEY"

curl --fail-with-body --silent --show-error \
  -X POST "$PUSHYOU_API_URL/v1/conversations/$PUSHYOU_CONVERSATION_ID/events/YOUR_EVENT_ID/ack" \
  -H "Authorization: Bearer $PUSHYOU_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{}'

Solicitar aprobación

curl --fail-with-body --silent --show-error \
  -X POST "$PUSHYOU_API_URL/v1/conversations/$PUSHYOU_CONVERSATION_ID/tasks" \
  -H "Authorization: Bearer $PUSHYOU_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"id":"docs-report-01","title":"Review the weekly report","category_id":"reports","fields":[{"id":"notes","label":"Review notes","type":"multiline","required":false}]}'

Las tareas reúnen aprobación y resultado. Tras la aprobación del propietario, un proceso consulta eventos con task_protocol=1, guarda su token de ejecución y reclama el intento. Mantiene la concesión con heartbeat y guarda el resultado real antes de complete. Completar también confirma el evento; un ACK independiente no termina una tarea pendiente.

Webhooks

También hay webhooks de respuesta firmados. Configúralos en los ajustes de Webhooks de respuesta de la app móvil. Verifica la firma del cuerpo original y evita duplicados por ID de entrega. HTTP 2xx confirma recepción, no finalización de la tarea. La guía de flujos detalla firmas y reintentos.

05Archivos y vistas

Los archivos usan un endpoint de medios separado y la misma clave REST con media:write o media:read. Sube primero los bytes originales y adjunta el ID a un mensaje de la misma sala. Las URL son privadas y requieren autorización. El límite es 10 MiB por imagen y 25 MiB por vídeo.

curl --fail-with-body --silent --show-error \
  "$PUSHYOU_MEDIA_URL/v1/media/docs-image-01?conversation_id=$PUSHYOU_CONVERSATION_ID" \
  -H "Authorization: Bearer $PUSHYOU_API_KEY" \
  -H 'Content-Type: application/octet-stream' \
  -H 'X-Pushyou-Filename: review.png' \
  --data-binary @review.png

curl --fail-with-body --silent --show-error \
  -X POST "$PUSHYOU_API_URL/v1/conversations/$PUSHYOU_CONVERSATION_ID/messages" \
  -H "Authorization: Bearer $PUSHYOU_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"id":"docs-attachment-01","text":"Please review this image.","attachment_ids":["docs-image-01"]}'

En MCP, llama a pushyou_prepare_media_upload con media_id, filename, content_type, tamaño en bytes y SHA-256. Envía los bytes originales mediante POST a upload.url, con los encabezados específicos devueltos, en cinco minutos. Después envía attachment_ids. REST ofrece la misma preparación. No sustituyas la autorización de carga por una clave de cuenta o token OAuth MCP.

Publica una vista opcional report, actions o html con PATCH …/view y {"view": CARD}; {"view": null} la retira. Se abre desde su conversación. El HTML está aislado: sin red externa, credenciales de la app ni almacenamiento del navegador. Declara las acciones; generarán eventos en la misma sala.

Card =
  { type: "report", title: string, items: { title: string, body?: string, label?: string }[] }
| { type: "actions", title: string, body?: string, actions: { id: ID, label: string }[] }
| { type: "html", title: string, html: string, height?: integer, actions?: { id: ID, label: string }[] }

Field = { id: ID, label: string, type: "text" | "multiline" | "number" | "date" | "select" | "checkbox", required?: boolean, options?: string[], min?: number, max?: number }

06Referencia de endpoints

Añade cada ruta a la base de su grupo. Usa una clave Bearer del programa, salvo en cargas con autorización específica. Abre una fila para ver la estructura de la solicitud y sustituye los IDs de ejemplo.

{ media_id: ID, filename: string, content_type: string, size: integer, sha256: string }

GET /v1/me
→ { id, key_scope, permissions, conversation_ids }

{ id: ID, name: string, description?: string, kind?: string, view?: Card }

?limit=20&before=CURSOR
→ { conversations, next_cursor }

GET /v1/conversations/ROOM_ID
→ { conversation }

{ name?: string, description?: string, pinned?: boolean, active?: boolean, view?: Card | null }

{ id: ID, text?: string, attachment_ids?: ID[], card?: Card | null, notify?: boolean }

?limit=20&before=CURSOR
→ { messages, next_cursor }

GET /v1/conversations/ROOM_ID/messages/MESSAGE_ID
→ { message }

GET /v1/conversations/ROOM_ID/events/head
→ { cursor }

GET /v1/conversations/ROOM_ID/receiver-status
→ { receivers, checked_at }

{ sequence: positive_integer, state: "starting" | "receiving" | "processing" | "retrying" | "paused" | "stopped" | "needs_review" | "delivery_pending" }
instance_id: UUID v4

?after=0
?after=0&task_protocol=1
→ { events, next_cursor }

{}
→ { ok: true }

GET /v1/conversations/ROOM_ID/view
→ { view: Card | null }

{ view: Card | null }

?limit=20&before=CURSOR
&category_id=reports&conversation_id=ROOM_ID
&kind=received&status_group=attention
&result_pending=true
kind: received | action | saved
status_group: attention | progress | problems | complete
→ { history, next_cursor }

{ id: ID, title: string, body?: string, category_id?: ID, fields?: Field[], inputs?: object, expires_at?: integer, result_requires_review?: boolean }

GET /v1/conversations/ROOM_ID/tasks/TASK_ID
→ { task }

GET /v1/conversations/ROOM_ID/tasks/TASK_ID/versions
→ { versions: [{revision, title, body, fields, inputs, created_at, change_request}] }

{ request_id: ID, expected_revision: integer, change_request_id?: ID, body: string, title?: string, fields?: Field[], inputs?: object }
Only pending or changes_requested tasks can be revised. Approval is required for every new version.

{ request_id: ID, attempt: integer, execution_token: string }

{ request_id: ID, attempt: integer, execution_token: string }

{ request_id: ID, attempt: integer, execution_token: string, status: "succeeded" | "failed" | "needs_review", result: string, result_links?: [{label: string, url: HTTPS_URL}] }

GET /v1/conversations/ROOM_ID/actions
→ { actions }

{ title: string, description?: string, fields: Field[], category_id?: ID, active?: boolean, expected_revision?: ID }

POST upload.url
Headers: upload.headers
Body: original file bytes

Content-Type: application/octet-stream
X-Pushyou-Filename: URI_ENCODED_FILENAME
Body: original file bytes

Range: bytes=0-65535 (optional)
→ original file bytes

HEAD /v1/media/MEDIA_ID
→ Content-Type, Content-Length, Accept-Ranges

DELETE /v1/media/UNATTACHED_MEDIA_ID

07Solución de problemas

Los errores REST devuelven un estado distinto de 2xx y {"error": "…"}. El cliente muestra los errores MCP; revisa el error estructurado y los permisos de la conexión.