Verifying Successful Account Connection

Use one of the following methods to find out when your user’s account has connected successfully to Seam through your app:

If you’ve redirected your app to the Connect Webview, poll or use a webhook to determine when the Connect Webview has completed successfully. You can then retrieve the device or ACS associated with the newly-connected account.
If you’ve embedded the Connect Webview in an iframe, use event listening to determine when to close the iframe. You can then retrieve the device or ACS associated with the newly-connected account.

You do not need to delete a Connect Webview once a user completes it. Instead, you can simply ignore completed Connect Webviews.

Polling

Use the connect_webview_id to retrieve the Connect Webview instance. You can check the following properties:

Property	Value when connected successfully
`status`	`authorized`
`login_successful`	`true`

Also, once the connection is successful, the connect_webview object includes a connected_account_id. Code:

const updatedConnectWebview = await seam.connectWebviews.get({
  connect_webview_id: connectWebview.connect_webview_id,
})

curl -X 'GET' \
  'https://connect.getseam.com/connect_webviews/get' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d "{
  \"connect_webview_id\": \"${connect_webview_id}\"
}"

updated_connect_webview = seam.connect_webviews.get(created_connect_webview.connect_webview_id)

updated_connect_webview = seam.connect_webviews.get(
  connect_webview_id: connect_webview.connect_webview_id
)

$updated_connect_webview = $seam->connect_webviews->get(
  connect_webview_id: $connect_webview->connect_webview_id
);

var updatedConnectWebview = seam.ConnectWebviews.Get(
  connectWebviewId: connectWebview.connectWebviewId
);

Output:

{
  connect_webview_id: '12345678-1234-1234-1234-123456789012',
  status: 'authorized',
  login_successful: true,
  connected_account_id: '11111111-1111-1111-1111-222222222222',
  ...
}

{
  "connect_webview": {
    "connect_webview_id": "12345678-1234-1234-1234-123456789012",
    "status": "authorized",
    "login_successful": true,
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    ...
  },
  "ok": true
}

ConnectWebview(
  connect_webview_id='12345678-1234-1234-1234-123456789012',
  status='authorized',
  login_successful=True,
  connected_account_id='11111111-1111-1111-1111-222222222222',
  ...
)

<
  Seam::ConnectWebview:0x00438
    connect_webview_id="12345678-1234-1234-1234-123456789012"
    status="authorized"
    login_successful=true
    connected_account_id="11111111-1111-1111-1111-222222222222"
    ...
>

{
  "connect_webview_id": "12345678-1234-1234-1234-123456789012",
  "status": "authorized",
  "login_successful": true,
  "connected_account_id": "11111111-1111-1111-1111-222222222222",
  ...
}

{
  "connect_webview_id": "12345678-1234-1234-1234-123456789012",
  "status": "authorized",
  "login_successful": true,
  "connected_account_id": "11111111-1111-1111-1111-222222222222",
  ...
}

Webhook

When Seam successfully establishes the connection to the user’s device or ACS account, Seam emits a connected_account.connected event. This event includes a connect_webview_id property. To avoid polling, use a Seam webhook to monitor for a connected_account.connected event with a connect_webview_id that matches the connect_webview_id of the appropriate Connect Webview instance. Note that the connected_account.connected event also includes a connected_account_id property. For more information, see Webhooks.

{
  "event_id": "22222222-3333-4444-5555-666666666666",
  "event_type": "connected_account.connected",
  "connected_account_id": "11111111-1111-1111-1111-222222222222",
  "connect_webview_id": "12345678-1234-1234-1234-123456789012",
  "occurred_at": "2024-07-17T05:01:53.157Z",
  ...
}

Event Listening

When you host a Connect Webview in an HTML iframe, the iframe uses window.parent.postMessage to send messages to the parent window that is hosting the iframe. window.parent.postMessage is a cross-origin communication mechanism available in web browsers. Register an event listener for the parent window containing the iframe to monitor for message events. Specifically, listen for a connect_webview.login_succeeded event. This event indicates that Seam has successfully established the connection to the user’s device or ACS account. A connect_webview.login_failed event indicates that the account connection did not complete successfully. For example:

window.addEventListener(
  'message',
  (event) => {
    if (event.data?.event?.event_type === 'connect_webview.login_succeeded') {
      // Do something.
    }
  },
  false,
)

Once you have received a connect_webview.login_succeeded event, you can use webhooks or listen for any of the following useful connection-related events:

Event	Description
`connected_account.created`	A connected account has been imported into your Seam workspace.
`connected_account.connected`	Seam has established connection to or is reconnected to a connected account.
`connected_account.completed_first_sync`	Seam has finished the first sync of a connected account, and the corresponding devices or systems are now available.
`device.added`	A device was added to Seam or was re-added to Seam after having been removed.
`device.connected`	The status of a device changed from offline to online. That is, the `device.properties.online` property changed from `false` to `true`. Note that some devices operate entirely in offline mode, so Seam never emits a `device.connected` event for these devices.

Getting Started

Use Cases

Core Concepts

Capability Guides

UI Components

Developer Tools

Industry Guides

Device Manufacturer Guidance

Low-Level APIs

Verifying Successful Account Connection

Polling

Webhook

Event Listening

​Polling

​Webhook

​Event Listening

​Additional Connection-Related Events

Polling

Webhook

Event Listening

Additional Connection-Related Events