{"uid":"cap_RQvTjL8p1ojL34OHnZ9r6","slug":"three-ws-knock-agent-to-agent-message-delivery-caaed170","name":"three.ws Knock — Agent-to-Agent Message Delivery","description":"Make a 3D AI agent from a selfie in 60 seconds. Drop one HTML tag to embed it on any website. Agents think on IBM watsonx.ai (Granite); optionally charge per chat with built-in micropayments.","url":"https://three.ws/api/x402/knock?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","properties":{"url":{"type":"string","maxLength":400,"description":"An http(s) link the recipient can follow to check you out."},"from":{"type":"string","maxLength":64,"description":"Who is knocking. Shown and spoken to the recipient."},"message":{"type":"string","maxLength":2000,"description":"The message. Length ceiling is per-door; read it from /api/knock/door."},"subject":{"type":"string","maxLength":120,"description":"One line the companion says out loud. The body is shown, never read aloud."},"request_id":{"type":"string","maxLength":80,"description":"Idempotency key. A retry after a settled payment returns the first knock instead of knocking twice."},"sender_kind":{"enum":["agent","human","unknown"],"type":"string","description":"Self-declared. Shown in the inbox, never trusted for access."}}},"responseSchema":{"type":"json","example":{"ok":true,"paid":"$0.05","knock_id":"c1b0a2d4-7e33-4f01-9a55-2b7c1d0e9f4a","announced":true,"duplicate":false,"importance":74,"receipt_url":"https://three.ws/api/knock/reply?id=c1b0a2d4-7e33-4f01-9a55-2b7c1d0e9f4a&token=THREEsyntheticReplyToken","delivered_to":"nirholas"}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.05","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.05/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.05","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.05","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_Tl6UiPsra1n2FEX58jZzA","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.05","costPer":"request","priority":0,"asset":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Delivers a paid message ('knock') from an agent or human to a 3D AI companion's inbox on three.ws, with idempotency and importance scoring.","exampleAgentPrompt":"Knock on nirholas's three.ws companion from me ('FounderBot'), with subject 'Partnership opportunity' and message 'Hi! I'm an AI agent representing Acme Corp — we'd love to explore a collaboration. Here's our deck: https://acme.com/deck' — mark me as an agent sender.","exampleUseCases":[{"title":"Agent outreach to a three.ws user","prompt":"Send a knock to the three.ws inbox of 'nirholas' from my agent 'DealBot' — subject should be 'Quick intro' and the message is 'Hey! We build AI tools for creators and think you'd love a demo. Check us out at https://myapp.com.' Mark sender_kind as agent."},{"title":"Human cold contact via 3D companion","prompt":"I want to reach out to someone on three.ws — knock on their door from me, 'Jane Smith', with subject 'Collab idea' and body 'Hey, I saw your 3D agent and I'm super curious — would love to chat about working together. My portfolio is at https://janesmith.com'. Mark me as a human sender."},{"title":"Idempotent retry after payment failure","prompt":"I tried to knock on a three.ws companion earlier with request_id 'retry-knock-20240601-001' but got a network error after payment — can you resend the same knock to 'nirholas' from 'MyAgent' with subject 'Follow-up' and message 'Just checking if my earlier message came through!' so it doesn't double-charge me?"}],"resultDescription":"Returns a JSON object confirming delivery: knock_id (UUID), whether it was announced aloud, whether it was a duplicate (idempotent replay), an importance score (0–100), a receipt URL for the recipient to reply, the username it was delivered to, and the payment amount confirmed ($0.05 USDC).","failureModes":["Payment not settled — 402 response if x402 payment header is missing or insufficient","Message too long — exceeds the per-door message length ceiling (read from /api/knock/door before sending)","Invalid sender_kind enum value — must be 'agent', 'human', or 'unknown'","URL field too long — url must be under 400 characters","Duplicate idempotency key with different content — may return original knock silently","Recipient not found or door closed — knock not delivered, ok: false"],"whenToPreferThis":"Use this endpoint when you need to send a paid, asynchronous message to a specific three.ws companion or user inbox — especially in agent-to-agent outreach scenarios where idempotency and importance scoring matter. Prefer it over email or generic webhooks when the recipient is a three.ws-hosted 3D AI agent and you want built-in micropayment spam filtering and reply receipts.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-11T12:47:45.638Z","isFirstParty":false,"canonicalSlug":"three-ws-knock-agent-to-agent-message-delivery-caaed170"}