Documentation

1. Sign up and create an instance

1. Register at /register.
2. Verify your email (check spam if it doesn't arrive).
3. Log in. You land on your dashboard.
4. Click Create new instance. Give it a display name.

2. Embed Alex on your site

Each instance exposes a one-line script snippet on its detail page. Paste it into your site's HTML, ideally just before </body>:

<script src="https://alex.siimii.ai/embed/v1/widget.js"
        data-instance-key="YOUR-INSTANCE-KEY"
        defer></script>

Optional attributes on the script tag:

• data-position — bottom-right (default) or bottom-left
• data-button-text — launcher button label (default "Ask Alex")
• data-open — auto (default), open, or closed

For iframe embeds without the launcher, point an iframe at /widget?instance_key=YOUR-INSTANCE-KEY.

3. Configure persona and knowledge

On your instance detail page:

• Persona instructions — plain English system prompt. Tell Alex who it is, how to speak, what to refuse.
• Voice — pick from the platform-allowed realtime voices.
• Escalation email — where human-follow-up requests are sent.
• Knowledge base — add entries (title + content + tags). Alex consults this before answering factual questions.

4. Optional: inbound phone calls

To let Alex answer a real phone number:

1. Complete KYC verification on /dashboard/verification.php (Stripe Identity, takes ~2 minutes).
2. On your instance page → Phone tab → search Telnyx inventory by country / area / locality → click Provision on a number you want.
3. The number starts routing inbound calls to Alex voice within seconds.

5. Handoff to a human on phone

Two modes per instance:

• Tenant SIP URI — paste your existing PBX address (e.g. sip:help@your-pbx.example.com). Alex transfers live calls there when it decides to escalate.
• Our PBX (agents) — add one or more agents on /dashboard/agents.php. Each gets a SIP credential. Agent installs Linphone / Zoiper with the credentials and keeps the app running. Alex rings them when escalating.

If no human answers within your timeout (10–180 s), Alex retakes the call, apologises, and collects contact info for email follow-up.

Set operator opening hours + holidays on the instance page to avoid ringing agents outside their shift.

6. Billing

• Plan fee — monthly Stripe subscription per instance (Free / Pro Starter / Business Scale).
• Usage overages — deducted from a prepaid balance. Top up on /dashboard/balance.php. Configure auto-recharge when you cross a threshold.
• Phone bridges — passed through from Telnyx with markup, only charged for answered bridges.

7. API (for advanced use)

The account-service exposes a REST API at /account-api/. Authenticate with your JWT (cookie from login or Authorization: Bearer). Key endpoints:

• GET /account-api/tenants/:tenantId/instances
• POST /account-api/tenants/:tenantId/instances
• PATCH /account-api/instances/:id
• POST /account-api/instances/:id/pause · .../resume
• POST /account-api/instances/:id/telnyx/provision
• GET /account-api/tenants/:tenantId/kyc
• POST /account-api/payment/checkout-session
• GET /account-api/billing

Scopes and request-ID correlation headers (X-Request-Id) are propagated end-to-end across web, account-service, and voice-gateway.

8. Security

• JWT cookies are HttpOnly + Secure + SameSite=Strict on the dashboard.
• Dashboard forms carry CSRF tokens validated server-side.
• Per-IP rate limits on auth and widget chat endpoints.
• Stripe Identity KYC is required for any telephony provisioning.

9. Support

Questions? Reply to any email you receive from the platform, or escalate from inside Ask Alex itself — the message lands on our dashboard.