# Connect and status

> Let users connect a WhatsApp number through QuickLink, and show the state of the browser's Polymorfa connection.

## Connect WhatsApp button

`ConnectWhatsAppButton` asks your server route to create a
[QuickLink](https://docs.polymorfa.com/numbers/quicklink), then opens Polymorfa's hosted pairing
page. The pairing screens are never embedded in your page, and the browser
receives only the hosted URL.

**React**

```tsx
<PolymorfaProvider tokenEndpoint="/api/polymorfa/token">
  <ConnectWhatsAppButton target="popup" onConnect={(link) => track(link.id)} />
</PolymorfaProvider>
```

**Web Components**

```html
<pmfa-connect-whatsapp target="popup" label="Connect your number"></pmfa-connect-whatsapp>
```

Your route decides which QuickLink to create. Add `connect` to
`createPolymorfaHandler` and allow `connect_whatsapp` in the user's grant:

```ts
createPolymorfaHandler({
  // ...
  mint: (user) => ({
    session: "support",
    conversations: [],
    allow: ["connect_whatsapp"],
  }),
  connect: ({ user }) => ({ externalId: user.id }),
});
```

`connect` returns the QuickLink input: `projectId`, `customerId`, `externalId`
or `configuration`. See [Create QuickLink](https://docs.polymorfa.com/api/quicklinks/create-quick-link)
for the fields. The button is hidden unless the grant allows
`connect_whatsapp`.

### Props

All 7 `ConnectWhatsAppButton` props, with types, defaults and a live preview, are on the [ConnectWhatsAppButton](https://docs.polymorfa.com/ui-kit/components/connect-whats-app-button) page.

### pmfa-connect-whatsapp

| Attribute or property | Type | Default | Description |
| --- | --- | --- | --- |
| `target` | `redirect` or `popup` | `redirect` | Where the hosted page opens. |
| `label` | `string` | "Connect WhatsApp" | Button label. |
| `client` | `PolymorfaClient` | The `definePolymorfa()` client | Client used to call your route. |
| `configuration` | `{ appearance?, locale?, stylesheet? }` | | Appearance, text and extra CSS. |

| Event | `detail` | When |
| --- | --- | --- |
| `pmfa-connect` | `{ url, id, expiresAt }` | The QuickLink is created and opened. |
| `pmfa-error` | The error | The QuickLink cannot be created. |

### Behavior

While the request runs, the button reads "Opening…", is disabled and sets
`aria-busy`. If the request fails, an alert below the button reads "Could not
start the connection. Try again." and a `popup` tab that was opened is closed.
The hosted URL must use `https`; any other response is treated as an error.

To build your own control, call `connectWhatsApp(client, options)` from
`@polymorfa/browser`. It takes the same `target`, `open` and an abort `signal`.

## Session status

`SessionStatus` shows the state of the browser's connection to Polymorfa: the
provider's client token. It does not show whether a WhatsApp number is
connected.

**React**

```tsx
<SessionStatus />
```

**Web Components**

```html
<pmfa-session-status></pmfa-session-status>
```

| State | Label |
| --- | --- |
| `idle` | Not connected |
| `loading` | Connecting |
| `ready`, `refreshing` | Connected |
| `retrying` | Reconnecting |
| `unauthenticated` | Signed out |
| `error` | Connection problem |

In the `retrying`, `unauthenticated` and `error` states, the badge shows a Retry
button that requests a new token.

All 3 `SessionStatus` props, with types, defaults and a live preview, are on the [SessionStatus](https://docs.polymorfa.com/ui-kit/components/session-status) page.

`<pmfa-session-status>` takes `client` and `configuration` properties.

### Accessibility

The badge is a status region named "Polymorfa connection: {state}", so screen
readers announce changes. The colored dot is decorative; the state is always
written out.

## Related

- [QuickLink](https://docs.polymorfa.com/numbers/quicklink)
- [Installation and setup](https://docs.polymorfa.com/ui-kit/setup)
