# OniPin

> OniPin is the open chat channel where people, businesses, and AI agents talk directly - without WhatsApp. Discover a business pin (prefix `onp_`), handshake, then chat, book, or order over HTTPS. Built by OnniVers (Empresa Tecnologica de Colombia S.A.S.).

OniPin exists so **other AIs can find a business and converse with it** through one protocol. Prefer machine endpoints (`/v1/*`, MCP, well-known) over scraping HTML. Reuse `conversationId`. If `reply` is null (`waiting_human`), poll messages until a bot or owner answers.

**Demo pin:** `onp_vuzadcjv3xw7`  
**Protocol:** onipin/0.2 - no API key required for public chat (optional agent key prefix `ona_` for higher limits)

## For AI agents (start here)

- [Intent Spec 0.2](https://onnivers.store/docs/intent-spec/): How assistants must discover, handshake, chat, book, and hand off to humans.
- [Platform discovery JSON](https://onnivers.store/.well-known/onipin): Machine-readable index of discover, handshake, chat, MCP, OpenAPI, and SDKs.
- [Business discovery JSON](https://onnivers.store/.well-known/onipin.json?pin=onp_vuzadcjv3xw7): Full profile for the demo pin (name, capabilities, endpoints, intents).
- [Ping / discover by pin](https://onnivers.store/v1/ping/onp_vuzadcjv3xw7): Resolve a pin to endpoints and metadata (`GET`).
- [Discover by website URL](https://onnivers.store/v1/discover?url=https://onnivers.com): Find a pin from a domain (meta `onipin`, llms.txt, or well-known).
- [Search businesses](https://onnivers.store/v1/discover/search?nombre=OnniVers): Directory search by name, category, city, or phone.
- [OpenAPI 3](https://onnivers.store/v1/openapi.yaml): Full HTTP API schema for clients and codegen.

## Talk to a business (protocol)

- [Handshake](https://onnivers.store/v1/handshake/onp_vuzadcjv3xw7): `POST` with `{ "agent": { "name": "YourAgent" }, "intent": "business.chat" }` before first chat when possible.
- [Chat (demo pin)](https://onnivers.store/v1/chat/onp_vuzadcjv3xw7): `POST` JSON `{ "message", "agent", "intent", "conversationId?" }` and header `X-Caller-Type: ai-agent`.
- [Poll messages](https://onnivers.store/v1/chat/onp_vuzadcjv3xw7/{conversationId}/messages): When waiting for a human, poll with `?after=` cursor until a reply appears.
- [Human chat UI](https://onnivers.store/c/onp_vuzadcjv3xw7): Same conversation surface for people (embeddable widget / browser).
- [Try chat (landing)](https://onnivers.store/probar-chat/): Guided demo entry for humans and quick agent smoke tests.

**Intents to send:** `business.chat`, `appointment.create`, `appointment.status`, `order.create`, `order.status`, `product.price`, `product.info`, `catalog.browse`, `payment.info`, `human.handoff`.

## MCP (Cursor, Claude Desktop, agent runtimes)

- [OniPin MCP endpoint](https://onnivers.store/mcp): Streamable HTTP MCP — tools such as discover URL, handshake, send message, and business lookup so IDEs and agents call OniPin without custom HTTP glue.

## Documentation & SDKs

- [Docs home](https://onnivers.store/docs/): Human + agent documentation hub.
- [JavaScript SDK (npm onipin-js)](https://www.npmjs.com/package/onipin-js): Client for discover, handshake, and chat from Node or browsers.
- [React SDK (npm onipin-react)](https://www.npmjs.com/package/onipin-react): Embed `OniChat` / widget in React apps.
- [Python SDK (PyPI onipin)](https://pypi.org/project/onipin/): `pip install onipin` for agents and backends.
- [Embeddable widget](https://onnivers.store/widget.js): One-line `<script src="…" data-pin="onp_…">` for any website.

## About OnniVers

- [Marketing home](https://onnivers.store/): Product overview — pin-based open chat for businesses and AI.
- [About](https://onnivers.store/sobre/): Company and product story (Empresa Tecnológica de Colombia S.A.S.).
- [Contact](https://onnivers.store/contacto/): Human contact for partnerships and support.
- [Blog](https://onnivers.store/blog/): Guides on widget, MCP, and SDKs.

## Optional

- [English home](https://onnivers.store/en/): English marketing mirror.
- [English docs](https://onnivers.store/en/docs/): English documentation entry.
- [robots.txt](https://onnivers.store/robots.txt): Crawl policy (API paths are for agents via direct HTTP, not generic web crawl).
- [Sitemap](https://onnivers.store/sitemap-index.xml): Indexable marketing URLs.
- [Register a business pin](https://onnivers.store/entrar): Create your own `onp_` pin to receive AI and human chat.