# Welcome screen

Show your name, logo and colours before the platform's consent screen, per link or for every connect in the workspace.

The welcome screen is a short page Pozy shows before sending the user to the platform. It says who is asking ("Acme wants to connect to your Instagram"), with your logo, and forwards to the platform's consent screen after about a second. Users who can see whose app is asking finish the connect more often.

The same branding carries through to the picker (Pages, locations, boards) and to the closing screen, so the whole flow looks like part of your product.

## Turn it on for one link

Add `welcome=true` and your brand to the connect call:

```bash cURL
curl "https://api.pozy.ai/v1/connect/instagram?profileId=6650c1f2a9e4b7d3c8a1f0e2&welcome=true&brandName=Acme&logoUrl=https://acme.com/logo.png&primaryColor=%234F46E5&redirect_url=https://app.example.com/connected" \
  -H "Authorization: Bearer $POZY_API_KEY"
```
```ts Node
const res = await fetch("https://api.pozy.ai/v1/connect/instagram?profileId=6650c1f2a9e4b7d3c8a1f0e2&welcome=true&brandName=Acme&logoUrl=https:%2F%2Facme.com%2Flogo.png&primaryColor=%234F46E5&redirect_url=https:%2F%2Fapp.example.com%2Fconnected", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
// data.authUrl now opens the welcome screen on pozy.ai
```
```python Python
resp = requests.get(
    "https://api.pozy.ai/v1/connect/instagram",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={
        "profileId": "6650c1f2a9e4b7d3c8a1f0e2",
        "welcome": "true",
        "brandName": "Acme",
        "logoUrl": "https://acme.com/logo.png",
        "primaryColor": "#4F46E5",
        "redirect_url": "https://app.example.com/connected",
    },
    timeout=30,
)
```

The returned `authUrl` points at the welcome screen instead of the platform. Nothing else in your flow changes.

## Save it for the whole workspace

Save your branding once and every connect URL created with your keys shows it, with no extra parameters. Do it in the dashboard under **Settings → White label**, or with the API:

```bash
curl -X PUT "https://api.pozy.ai/v1/connect/welcome-screen" \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "showByDefault": true,
    "brandName": "Acme",
    "logoUrl": "https://acme.com/logo.png",
    "theme": {
      "primaryColor": "#4F46E5",
      "heading": "Connect {platform} to {brand}",
      "trustLine": "{brand} only gets the access you approve. Disconnect any time.",
      "cornerRadius": 12,
      "font": "sans",
      "termsUrl": "https://acme.com/terms",
      "privacyUrl": "https://acme.com/privacy"
    }
  }'
```

`showByDefault` is required. `GET /v1/connect/welcome-screen` returns what is saved. Changing the saved screen needs a workspace owner or admin, or a full-scope API key. Profile-scoped keys cannot change it.

## How the options combine

| You send | Result |
| --- | --- |
| Nothing, nothing saved | No welcome screen. `authUrl` goes straight to the platform. |
| Nothing, saved with `showByDefault: true` | The saved screen. |
| `welcome=true` | The screen, with your parameters over the saved branding (theme merged key by key). |
| `welcome=false` | No screen for this link, even if one is saved. |
| `handoff=true` | Always the screen: it is the first thing the phone shows. See [Phone handoff](https://pozy.ai/docs/connect/phone-handoff). |
| `headless=true` | No screen, unless `handoff=true`. `welcome=true` with `headless=true` is rejected. |

Branding parameters (`brandName`, `logoUrl`, `primaryColor`, `welcomeTheme`) only apply when the screen is shown. Sending them on a link without the screen returns `400 invalid_field_value` with `param: welcome`, so you notice instead of wondering why your logo is missing.

## Branding parameters

| Parameter | Limit |
| --- | --- |
| `brandName` | 1 to 60 characters. |
| `logoUrl` | An `http(s)` URL, up to 2,048 characters. |
| `primaryColor` | `#RRGGBB`. URL-encode the `#` as `%23` in a query string. |
| `welcomeTheme` | A JSON object with any of the theme keys below, up to 4,000 characters once encoded. |

## Theme keys

The same keys work in `welcomeTheme` on a link and in `theme` on the saved screen.

| Key | Type | Notes |
| --- | --- | --- |
| `heading` | text, up to 120 | Default: "{brand} wants to connect to your {platform}". |
| `trustLine` | text, up to 200 | The reassurance line under the heading. |
| `consentLine` | text, up to 200 | What happens next on the platform. |
| `statusLine` | text, up to 200 | Shown while forwarding. Default: "Taking you to {platform}". |
| `buttonLabel` | text, up to 30 | The fallback button if the forward stalls. Default: "Continue to {platform}". |
| `successHeading`, `errorHeading` | text, up to 120 | Closing screen titles. |
| `successBody`, `errorBody` | text, up to 200 | Closing screen text. |
| `primaryColor`, `accentColor`, `pageColor`, `cardColor`, `textColor` | `#RRGGBB` | Button, icons, page background, card background and text. |
| `cornerRadius` | integer, 0 to 24 | Card and button radius in pixels. |
| `font` | `sans`, `serif` or `mono` | |
| `bannerStyle` | `halftone`, `solid` or `plain` | The band at the top of the card. |
| `trustLineIcon`, `consentLineIcon` | `shield`, `lock`, `link`, `check`, `user`, `sparkles` or `none` | |
| `hide` | list | Any of `heading`, `trustLine`, `consentLine`, `statusLine`, `successBody`, `errorBody`. |
| `termsUrl`, `privacyUrl` | `https://` URL | Linked in the footer. |

`{brand}` and `{platform}` in any text are replaced with your brand name and the platform's name. Unknown keys are rejected, so a typo fails loudly.

> **Keep it short:**
> 
> The screen is on view for about a second before it forwards. Put the reassurance in `trustLine` and keep `heading` to one line.

## Endpoints

| Endpoint | What it does |
| --- | --- |
| [`GET /v1/connect/welcome-screen`](https://pozy.ai/docs/api/getConnectWelcomeScreen) | Get the saved welcome screen |
| [`PUT /v1/connect/welcome-screen`](https://pozy.ai/docs/api/updateConnectWelcomeScreen) | Save the welcome screen |
| [`GET /v1/connect/{platform}`](https://pozy.ai/docs/api/getConnectUrl) | Get OAuth connect URL |