Documentation

Build with OniPin

Install the chat, connect AIs via HTTP or MCP. Examples use sample pin onp_tu_pin.

What you can use today (MCP, SDK, HTTP)

Real production platform. You only need the business pin.

  • MCP — https://onnivers.store/mcp (Cursor, Claude)
  • JS SDK — npm install onipin-js
  • React — npm install onipin-react (OniChat)
  • Python SDK — pip install onipin
  • HTTP /v1 + OpenAPI — https://onnivers.store/v1/openapi.yaml
  • Widget — /widget.js
Cursor MCP 
{
  "mcpServers": {
    "onipin": { "url": "https://onnivers.store/mcp" }
  }
}

Get started with OniPin

  1. Sign up for free and confirm your email.
  2. In MY AI, configure business info, FAQs, and catalog.
  3. Share https://onnivers.store/c/onp_tu_pin or install the widget.
  4. In CHATS, take over whenever you want.

Install chat on your website

HTML 
<script src="https://onnivers.store/widget.js" data-pin="onp_tu_pin"></script>

React (official package)

React 
npm install onipin-react

import { OniChat } from "onipin-react";

<OniChat pin="onp_tu_pin" />
<OniChat pin="onp_tu_pin" mode="iframe" height={640} />

HTTP /v1 protocol

GET /v1/ping/{pin}

Business discovery.

curl 
curl https://onnivers.store/v1/ping/onp_tu_pin
POST /v1/chat/{pin}

Send a message; returns conversationId and reply.

curl 
curl -X POST https://onnivers.store/v1/chat/onp_tu_pin \
  -H "Content-Type: application/json" \
  -H "X-Caller-Type: ai-agent" \
  -d '{ "message": "What are your hours?" }'
GET /v1/catalog/{pin}

Public catalog of products and services.

Discovery and Intent Spec (AI ↔ business)

Guide for assistants: How an AI decides to use OniPin

meta tag 
<meta name="onipin" content="onp_tu_pin">
platform well-known 
curl "https://onnivers.store/.well-known/onipin"
business well-known 
curl "https://onnivers.store/.well-known/onipin.json?pin=onp_tu_pin"
discover from URL 
curl "https://onnivers.store/v1/discover?url=https://example.com"
handshake 
curl -X POST https://onnivers.store/v1/handshake/onp_tu_pin \
  -H "Content-Type: application/json" \
  -d '{"agent":{"name":"MyBot"},"intent":"appointment.create"}'

Intent Specification 0.2

How an AI decides to use OniPin

The user says "book an appointment" — not "use OniPin". This spec defines the flow any assistant can implement.

5-step flow

  1. Discover — Does the business publish OniPin? (/v1/discover, onipin meta, llms.txt)
  2. Handshake — Announce agent + intent (POST /v1/handshake/{pin})
  3. Send message — POST /v1/chat/{pin}
  4. Receive reply — Text + conversationId
  5. Action — Booking/order in Agenda (data.bookingId / orderId)

Discover from URL

curl 
curl "https://onnivers.store/v1/discover?url=https://onnivers.store/probar-chat/"

Handshake

curl 
curl -X POST https://onnivers.store/v1/handshake/onp_vuzadcjv3xw7 \
  -H "Content-Type: application/json" \
  -d '{"agent":{"name":"MyBot","version":"1.0"},"intent":"appointment.create"}'

Chat with intent

curl 
curl -X POST https://onnivers.store/v1/chat/onp_vuzadcjv3xw7 \
  -H "Content-Type: application/json" \
  -H "X-Caller-Type: ai-agent" \
  -d '{"message":"I want a demo on Friday","agent":{"name":"MyBot"},"intent":"appointment.create"}'

Intents

  • business.chat — general conversation
  • appointment.create — appointment / demo
  • order.create — order
  • product.price — pricing
  • catalog.browse — catalog
  • payment.info — payment

Demo pin:onp_vuzadcjv3xw7

MCP server

Endpoint https://onnivers.store/mcp — Endpoint — uses POST (Streamable HTTP). Not a web page; connect from Cursor or Claude.

  • descubrir_url, handshake, buscar_negocio, enviar_mensaje
  • leer_conversacion, obtener_catalogo, crear_reserva, comprar_producto
.cursor/mcp.json 
{ "mcpServers": { "onipin": { "url": "https://onnivers.store/mcp" } } }

SDK (npm + React + PyPI)

install 
npm install onipin-js
npm install onipin-react
pip install onipin
sdk.mjs 
import { OniPinClient } from "onipin-js";

const oni = new OniPinClient({
  baseUrl: "https://onnivers.store",
  pin: "onp_tu_pin",
  callerType: "ai-agent",
});

const info = await oni.ping();
await oni.handshake("appointment.create");
const chat = await oni.chat("I want a demo on Friday", { intent: "appointment.create" });
console.log(chat.reply?.text);
OniChat.tsx 
import { OniChat } from "onipin-react";

export function Support() {
  return <OniChat pin="onp_tu_pin" />;
}
sdk.py 
from onipin import OniPinClient

oni = OniPinClient(pin="onp_tu_pin", agent={"name": "MyBot", "version": "1.0"})
oni.handshake("business.chat")
print(oni.chat("I want a demo on Friday", intent="business.chat").get("reply"))

onipin-js · onipin-react · onipin (PyPI) · OpenAPI