amerc Hotline

1. Trust model

The hosted iframe and customer page are separate origins. The SDK accepts messages only from the exact Hotline origin and iframe window. amerc signs a short-lived iframe ticket bound to the app, customer origin, and client session. APIs and JavaScript functions are deny-by-default and become available only after the page registers them.

Same-origin API skills run in the customer page with credentials: 'include'. The browser attaches eligible cookies, including HttpOnly cookies, directly to the site request. Cookie values are never read or copied to amerc, the iframe, Tinypool, or the agent.

2. Create a profile, embed, and register skills

Every signed-in customer can open Dashboard → Hotline → Manage. Create a customer-facing profile, exact origins, welcome message, and additive reception system prompt; then copy the embed tag.

<script src="https://amerc.lessokaji.com/hotline/sdk.js?app=YOUR_EMBED_KEY"></script>
<script>
registerHotlineSkills({
  description: 'Customer account page',
  apis: [{ name: 'accountStatus', method: 'GET', endpoint: '/api/account/status' }],
  funcs: [{
    name: 'showNotice',
    description: 'Put supplied text in the visible notice area.',
    handler: text => {
      document.querySelector('#notice').textContent = String(text);
      return { shown: true };
    }
  }]
});
hotline.open();
</script>

API methods are limited to GET/POST, targets must stay on the parent page origin, authorization/cookie headers are stripped, and responses, bodies, arguments, concurrency, rates, and time are bounded. Registered functions receive JSON arguments; arbitrary page evaluation is not exposed.

3. CSP, CORS, and framing

Allow the SDK in script-src and the hosted chat in frame-src. amerc returns a per-app frame-ancestors policy. The SDK itself is CORS-readable; customer APIs remain same-origin and need no CORS relaxation. Do not add amerc to connect-src unless your page CSP blocks the SDK iframe’s own connection indirectly.

4. Run Tinypool

node bin/tinypool.js   --server wss://amerc.lessokaji.com/hotline/ws   --token YOUR_ONE_TIME_POOL_TOKEN   --provider codex --capacity 4 --workdir /srv/customer-support

The user workspace can download a self-contained reception software pack with launchers and private configuration. Creating a Hotline provides a dedicated starter pool; another pool can be assigned to several of the same tenant’s Hotlines for shared capacity. Providers are explicit: codex uses non-interactive full-access execution equivalent to the local YOLO form; claude uses claude --dangerously-skip-permissions --print; tinybox-consumer requires an operator-supplied activation command. Each leased browser session gets an isolated agent context; prompts never overlap, and the first prompt carries system instructions, the registered skill schema, and the user’s first message together.

5. Traffic and billing

The authoritative amerc browser relay meters UTF-8 wire bytes once. Every billable message has an idempotent event ID, so a retry or reconnect replay does not add traffic twice. Dashboard → Hotline shows the signed-in tenant’s profiles, pools, live sessions, usage, and charge. Admin → Hotline adds global account/app/site/day breakdowns and pricing configuration.

6. Health and troubleshooting

• GET /hotline/health — service version, pools, active and waiting sessions.
• Tinypool local GET /health — relay state, provider, capacity, sessions.
• Waiting: start the newest downloaded pool package or increase capacity.
• Origin rejected: add the page’s exact scheme/host/port to the app allowlist.
• Cookie appears uncookied: confirm the API is same-origin, the cookie path/domain/SameSite rules apply, and the page did not register a cross-origin endpoint.
• CSP blocked: allow the SDK and frame URL without weakening frame-ancestors.

7. Live acceptance

1. Open mdcs.lessokaji.com/test/hotline.php.
2. Set the test cookie and ask the agent to fetch cookieState.
3. Ask it to call renderWebGPU and putVisibleText.
4. Send 請用中文回覆：熱線連線正常.
5. Close and reopen the widget, then briefly interrupt/restart Tinypool to observe reconnection.
6. Confirm the visible evidence log and Hotline usage totals.