Connect and status
Let users connect a WhatsApp number through QuickLink, and show the state of the browser's Polymorfa connection.
Customize
Explore with sample data. Messages, calls and template actions stay in this demo.
Connect WhatsApp button#
ConnectWhatsAppButton asks your server route to create a 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.
<PolymorfaProvider tokenEndpoint="/api/polymorfa/token">
<ConnectWhatsAppButton target="popup" onConnect={(link) => track(link.id)} />
</PolymorfaProvider>Your route decides which QuickLink to create. Add connect to createPolymorfaHandler and allow connect_whatsapp in the user's grant:
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 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 page.
pmfa-connect-whatsapp#
targetredirectorpopupWhere the hosted page opens.
Default
redirectlabelstringButton label.
Default "Connect WhatsApp"
clientPolymorfaClientClient used to call your route.
Default The
definePolymorfa()clientconfiguration{ 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.
<SessionStatus />| 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 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.