Skip to content
Shortcut: /, ⌘K or Ctrl+K

Connect and status

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

View as Markdown
Sample data
@polymorfa/react

Customize

Appearance
colorPrimary
colorBackground
colorForeground
colorMuted
colorBorder
colorDanger
colorSuccess
Props

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.

TSX
<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:

TypeScript
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#

  • targetredirect or popup

    Where the hosted page opens.

    Default redirect

  • labelstring

    Button label.

    Default "Connect WhatsApp"

  • clientPolymorfaClient

    Client used to call your route.

    Default The definePolymorfa() client

  • configuration{ appearance?, locale?, stylesheet? }

    Appearance, text and extra CSS.

EventdetailWhen
pmfa-connect{ url, id, expiresAt }The QuickLink is created and opened.
pmfa-errorThe errorThe 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.

TSX
<SessionStatus />
StateLabel
idleNot connected
loadingConnecting
ready, refreshingConnected
retryingReconnecting
unauthenticatedSigned out
errorConnection 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.