Custom Domains
Your customers are about to chat with your AI agent through chat.acme.com — not through a Perfox subdomain. By the end of this page, you'll have your own hostname live, with TLS issued automatically and your default Perfox subdomains still working as a fallback.
This page is for workspace admins — only admins see the Custom Domain tab in Settings.
How it works
Your workspace starts with a default pair of addresses: <slug>.perfox.ai for the Studio and chat, and <slug>-api.perfox.ai for the API. A custom domain sits on top of both — it does not replace them.
One custom domain serves everything same-origin: the Studio app, /api, /webhooks, the WebSocket, and the embeddable widget all answer on your hostname. Adding a custom domain is additive, so your <slug>.perfox.ai addresses keep working alongside it.
Once your domain is verified, it resolves to your workspace exactly like your default subdomains do. There is nothing to route or configure beyond the two DNS records below.
Adding a domain — worked example
Asha is an admin at Acme Support. She wants customers to reach the support chat at chat.acme.com instead of the default Perfox address.
Setup: Asha opens Admin → Settings → Custom Domain, types chat.acme.com under Domain and clicks Add domain. The domain appears as Pending DNS with two DNS records to create.
Action: She adds both records at her DNS provider — a CNAME pointing to the Perfox target shown on screen, and a TXT record containing the ownership token. Then she clicks Verify.
Result: The badge moves to Verified — issuing certificate and, within a few minutes, to Active. The chat widget and her API webhooks now answer on chat.acme.com.
What just happened: Perfox checked that the TXT token was present (proving domain ownership) and that the CNAME resolved correctly (proving routing). It then issued a TLS certificate automatically. From then on the domain routes to Asha's workspace the same way <slug>.perfox.ai always did.
Step by step
- Open Admin → Settings → Custom Domain, enter your domain (e.g.
chat.acme.com) and click Add domain. It appears as Pending DNS with a table of two records: a CNAME (name = your domain, value = the Perfox target) and a TXT ownership record. Each value has a copy button; TTL "Auto / 3600". - Create both records at your DNS provider.
- Click Verify. Perfox checks ownership (the TXT record) and routing (the CNAME), then advances the status. If a check fails, the reason is shown under the domain.
Status reference
| Badge | Meaning |
|---|---|
| Pending DNS | Added; waiting for you to create the DNS records and click Verify. |
| Verified — issuing certificate | Ownership and routing confirmed; certificate on its way. |
| Active | Live over HTTPS — the panel shows "Live — your workspace is reachable at https://…". |
| Action needed | Verification failed — check the reason shown, fix the DNS records and click Verify again. |
TLS
Certificates are issued and renewed automatically. There is nothing for you to upload or rotate.
Removing a domain
Click Remove to drop a domain; it stops resolving. Your default perfox.ai addresses are not affected.
Actions at a glance
| Action | What it does |
|---|---|
| List | See your domains and their current status. |
| Add domain | Adds the domain as Pending DNS and shows the CNAME and TXT records to create. |
| Verify | Re-check DNS ownership and routing; advance the status. |
| Remove | Remove a domain from your workspace. |
Next steps
You can now serve your widget, API, and Studio from your own domain with TLS managed for you.
- Embedding the Widget — place the same-origin embed snippet on your site now that your domain is active.
- Settings — the Custom Domain tab and the rest of Settings.