# Use your own domain for a hosted chat

> Serve the hosted chat at chat.yourcompany.com instead of a WelcomeAI address. Two DNS records.

Source: https://welcomeai.dev/docs/custom-domain
Category: Widgets
Updated: 2026-09-09

---
## What it does

A hosted chat page normally lives at a WelcomeAI address. With a custom domain it lives at yours --
`chat.yourcompany.com`, `ask.yourcompany.com`, whatever you like -- and nothing on the page says
otherwise. Same chat, same knowledge base, your address.

## What you need

- A widget with a hosted page. **Full page** widgets always have one; the address is shown on the
  Install tab as **Share link**.
- The **Business** plan.
- Access to the DNS of the domain you want to use. Not the website, the DNS: the panel where you add
  records at your registrar, or at Cloudflare, or wherever your domain is managed.
- A subdomain, ideally. See *Apex domains* below for the exception.
- Two records, both in the same DNS panel, in one sitting.

We never ask for your DNS credentials and never touch your zone. You create two records; that is the
whole of your side.

## Setting it up

1. Open the widget, go to **Install**, find **Custom domain**.
2. Type the hostname you want -- `chat.yourcompany.com` -- and press **Save**. Nothing is reserved and
   nothing is registered yet; the status says *Waiting for DNS*, which is the truth.
3. The panel shows **two** records. Create both in your DNS, in one visit.
4. Press **Check**. When both have travelled, the status becomes *Live*, the address becomes a link,
   and **Share link** at the top of the tab switches to your domain.

The certificate is issued automatically. There is nothing to buy, generate or upload, and nothing to
renew.

## The two records

**Step 1 proves the domain is yours.** A TXT record carrying a value that belongs to your widget and
to nothing else:

| Field | Value |
|---|---|
| Type | `TXT` |
| Name | `_welcomeai.chat.yourcompany.com` |
| Value | `welcomeai-domain-verification=...` -- the panel shows yours |

**Step 2 points the hostname at us.** For a subdomain, one CNAME:

| Field | Value |
|---|---|
| Type | `CNAME` |
| Name | `chat` (just the label, not the whole hostname) |
| Value | `cname.welcomeai.dev` |
| Proxy / CDN | **Off.** See below. |

The panel prints your exact values, and those are the ones to trust: they can differ from any example,
including this one.

## Why two

Because the second one cannot say *whose* the domain is. Every customer's CNAME points at the same
address, so a hostname pointed at us proves that somebody who controls that DNS wants it here -- not
which account it belongs to. The TXT value is unique to your widget, so publishing it is a statement
about your workspace and nobody else's.

Until that record is found, typing a hostname reserves nothing: anyone can type any name, and only
the workspace that publishes the token gets it. That is deliberate, and it is what stops somebody
claiming a name that is not theirs.

You can delete the TXT record once the domain is live. Leaving it costs nothing and makes
reconnecting later instant.

## Turn the proxy off

If your DNS is at Cloudflare, the record must be **DNS only** -- the grey cloud, not the orange one.
Other providers call the same thing a proxy, a CDN, or web forwarding.

This is the single most common reason a setup does not finish. With the proxy on, your domain resolves
to your CDN instead of to us, we never see the request, the check keeps saying *Waiting for DNS*, and
if it does connect you get a certificate error. Grey cloud, always.

## How long it takes

Usually a couple of minutes. It depends on the TTL of the record you replaced -- if a record already
existed on that name with a one-hour TTL, the old answer can be cached for up to an hour.

Nothing is lost while you wait. Press Check again whenever you like; opening the Install tab also
re-checks once on its own.

## Apex domains

An apex -- `yourcompany.com` with nothing in front -- cannot be a CNAME. That is a rule of DNS, not
ours. For an apex the panel shows **A** records instead, and you create those.

Some providers offer `ALIAS` or `ANAME`, which behaves like a CNAME at the apex. If yours does, point
it at `cname.welcomeai.dev` and you get the same benefit.

In practice most people use a subdomain, because an apex is usually already serving the main website.

## When it does not work

| What you see | Usually |
|---|---|
| *Step 1* will not pass | The TXT is on the wrong name -- it goes on `_welcomeai.` **plus the whole hostname** |
| *Step 1* says records exist but none is ours | A typo in the value, or it is another widget's token |
| *Waiting for DNS* long after you saved the records | The proxy is on, or the CNAME is on the wrong name |
| *Waiting for DNS* and the records look right | An old record is still cached; wait out its TTL |
| An error mentioning the domain is in use | The hostname is connected to another widget, or to another service |
| The address loads someone else's site | The record points somewhere else; check for a second record on the same name |
| A certificate warning | Almost always the proxy again |

`dig chat.yourcompany.com` and `dig TXT _welcomeai.chat.yourcompany.com` from a terminal, or any
online DNS lookup, tell you what the world currently sees. That is the fastest way to separate "the
record is wrong" from "the record has not travelled yet".

## What happens to the old address

It keeps working. The WelcomeAI address is still there and still answers, and the Install tab names it
underneath your domain. Links you already shared do not break.

## Removing it

**Remove** on the Custom domain card. The chat stops answering on that hostname immediately and the
WelcomeAI address goes back to being the one on Share link. Delete the DNS record afterwards at your
leisure -- leaving it costs nothing, but a record pointing at a service you no longer use is worth
tidying.

## What we can and cannot see

We see the hostname you typed and whether it resolves to us. We do not see your DNS credentials, your
other records, or anything else in your zone -- there is no integration with your DNS provider, and
there is nothing to authorise. You make the change; we only look at the public answer.