Connect widget

1. Create a session on your server#

Your server calls POST /v1/connect/sessions with a server key and your own reference for the user (up to 128 characters). The answer's session is single use and valid 15 minutes. The publishable key alone can never start a connection.

curl https://mcp.wagent.sh/v1/connect/sessions \
  -H "Authorization: Bearer wg_live_…" \
  -H "Idempotency-Key: <a unique id>" \
  -H "Content-Type: application/json" \
  -d '{"user":"your-user-id"}'

2. Open the widget on your page#

Pass the session to Wagent.connect() with your publishable key. The widget opens over your page and walks the user through linking the number and choosing chats.

<script src="https://app.wagent.sh/connect.js"></script>
<script>
  Wagent.connect({ key: 'wg_pub_…', session: '…' })
    .then((r) => {
      // r.type 'wagent:connected': r.session_id and r.phone; r.type 'wagent:exit': r.linked
    })
    .catch((e) => {
      // e.type 'wagent:error': e.code says why
    });
</script>

The promise resolves when the user connects (wagent:connected, with the session id and phone) or closes the widget (wagent:exit), and rejects with wagent:error and a code. No secret ever reaches your page.

Publishable key and allowed sites#

• The workspace has one publishable key (wg_pub_…), shown and rotated on the Developers screen.
• Only the sites you list may open the widget: exact origins such as https://example.com, https only (http only for localhost), up to 20.
• The workspace needs an active plan; without one, creating a session answers 409 widget_unavailable.
• Each connected number is billed to your workspace like your own, and carries your user reference as external_ref in GET /v1/sessions and in session webhooks.