Comment on page
Embedding a Connect Webview in Your App
Use redirection or an iframe to embed a Connect Webview in your app.
To incorporate a Connect Webview in your app using redirection, first create the Connect Webview. Redirect your app to the URL for the created Connect Webview. After your user has completed the Connect Webview, verify that your user has connected their device account successfully to Seam. Then, you can use the Seam API to control your users' connected devices.
When your user initiates an action in your app to connect their device account to Seam, create a Connect Webview (
connect_webview
object).When creating the new Connect Webview, note the following suggestions:
- Make sure to set a
custom_redirect_url
so that the Connect Webview redirects back to the desired page within your application after the Connect Webview flow completes.If you want to redirect to a different page when there is an error, you can set thecustom_redirect_failure_url
to the URL for the desired page. - We recommend setting
wait_for_device_creation
totrue
so that the Connect Webview does not complete until Seam completes the first sync of the connected account and devices.
Python
cURL (bash)
JavaScript
Ruby
C#
Java
Request:
created_connect_webview = seam.connect_webviews.create(
custom_redirect_url = "https://example.com/redirect",
custom_redirect_failure_url = "https://example.com/failure-redirect",
provider_category = "stable",
wait_for_device_creation = True
)
pprint(created_connect_webview)
Response:
ConnectWebview(workspace_id='398d80b7-3f96-47c2-b85a-6f8ba21d07be',
connect_webview_id='2c852289-ee42-49d0-bddc-0410b518003d',
status='pending',
url='https://connect.getseam.com/connect_webviews/view?connect_webview_id=2c852289-ee42-49d0-bddc-0410b518003d&auth_token=z7Wu2Lc85gYUbNUhdvCWaEhmQv61FziA',
login_successful=False,
device_selection_mode='none',
any_provider_allowed=False,
any_device_allowed=False,
created_at='2023-11-15T23:24:36.947Z',
custom_metadata={},
connected_account_id=None,
authorized_at=None,
custom_redirect_url='https://example.com/redirect',
custom_redirect_failure_url='https://example.com/failure-redirect',
accepted_providers=['august',
'avigilon_alta',
'brivo',
'schlage',
'smartthings',
'yale',
'nuki',
'salto',
'controlbyweb',
'minut',
'my_2n',
'kwikset',
'ttlock',
'noiseaware',
'igloohome',
'ecobee',
'hubitat',
'four_suites',
'dormakaba_oracode',
'lockly',
'wyze'],
accepted_devices=[],
selected_provider=None,
wait_for_device_creation=True,
automatically_manage_new_devices=True)
Request:
curl -X 'POST' \
'https://connect.getseam.com/connect_webviews/create' \
-H 'accept: application/json' \
-H 'Authorization: Bearer ${API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"custom_redirect_url": "https://example.com/redirect",
"custom_redirect_failure_url": "https://example.com/failure-redirect",
"provider_category": "stable",
"wait_for_device_creation": true
}'
Response:
{
"connect_webview": {
"url": "https://connect.getseam.com/connect_webviews/view?connect_webview_id=e386fe69-7bce-4796-bceb-44cc240fd604&auth_token=CvPDERYGGMvqgo6N1gsT7XRBieBtPqtUG",
"status": "pending",
"workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
"custom_metadata": {},
"accepted_devices": [],
"login_successful": false,
"selected_provider": null,
"accepted_providers": [
"august",
"avigilon_alta",
"brivo",
"schlage",
"smartthings",
"yale",
"nuki",
"salto",
"controlbyweb",
"minut",
"my_2n",
"kwikset",
"ttlock",
"noiseaware",
"igloohome",
"ecobee",
"hubitat",
"four_suites",
"dormakaba_oracode",
"lockly",
"wyze"
],
"any_device_allowed": false,
"connect_webview_id": "e386fe69-7bce-4796-bceb-44cc240fd604",
"custom_redirect_url": "https://example.com/redirect",
"any_provider_allowed": false,
"device_selection_mode": "none",
"wait_for_device_creation": true,
"custom_redirect_failure_url": "https://example.com/failure-redirect",
"automatically_manage_new_devices": true,
"created_at": "2023-11-15T23:25:47.222Z",
"authorized_at": null
},
"ok": true
}
Request:
const createdConnectWebview = await seam.connectWebviews.create({
custom_redirect_url: "https://example.com/redirect",
custom_redirect_failure_url: "https://example.com/failure-redirect",
provider_category: "stable",
wait_for_device_creation: true
})
console.log(createdConnectWebview)
Response:
{
url: 'https://connect.getseam.com/connect_webviews/view?connect_webview_id=28fa1da1-d4ab-454c-a622-3ca95f22028a&auth_token=2r2Rn8V5QUtxE79gNhTmTK58KkuqrwU8d',
status: 'pending',
workspace_id: '398d80b7-3f96-47c2-b85a-6f8ba21d07be',
custom_metadata: {},
accepted_devices: [],
login_successful: false,
selected_provider: null,
accepted_providers: [
'august', 'avigilon_alta',
'brivo', 'schlage',
'smartthings', 'yale',
'nuki', 'salto',
'controlbyweb', 'minut',
'my_2n', 'kwikset',
'ttlock', 'noiseaware',
'igloohome', 'ecobee',
'hubitat', 'four_suites',
'dormakaba_oracode', 'lockly',
'wyze'
],
any_device_allowed: false,
connect_webview_id: '28fa1da1-d4ab-454c-a622-3ca95f22028a',
custom_redirect_url: 'https://example.com/redirect',
any_provider_allowed: false,
device_selection_mode: 'none',
wait_for_device_creation: true,
custom_redirect_failure_url: 'https://example.com/failure-redirect',
automatically_manage_new_devices: true,
created_at: '2023-11-15T23:28:03.845Z',
authorized_at: null
}
Request:
created_connect_webview = client.connect_webviews.create(
custom_redirect_url: "https://example.com/redirect",
custom_redirect_failure_url: "https://example.com/failure-redirect",
provider_category: "stable",
wait_for_device_creation: true
)
puts created_connect_webview.inspect
Response:
<Seam::ConnectWebview:0x00438
url="https://connect.getseam.com/connect_webviews/view?connect_webview_id=c1350df4-278f-42cc-9c16-4f9e41103796&auth_token=6zrib4wrGZMDxvJxPQQFiB6snmx7UAU6E"
status="pending"
workspace_id="398d80b7-3f96-47c2-b85a-6f8ba21d07be"
custom_metadata={}
accepted_devices=[]
login_successful=false
selected_provider=nil
accepted_providers=["august", "avigilon_alta", "brivo", "schlage", "smartthings", "yale", "nuki", "salto", "controlbyweb", "minut", "my_2n", "kwikset", "ttlock", "noiseaware", "igloohome", "ecobee", "hubitat", "four_suites", "dormakaba_oracode", "lockly", "wyze"]
any_device_allowed=false
connect_webview_id="c1350df4-278f-42cc-9c16-4f9e41103796"
custom_redirect_url="https://example.com/redirect"
any_provider_allowed=false
device_selection_mode="none"
wait_for_device_creation=true
custom_redirect_failure_url="https://example.com/failure-redirect"
automatically_manage_new_devices=true
created_at=2023-11-15 23:31:12.082 UTC>
Request:
var createdConnectWebview = seam.ConnectWebviews.Create(
customRedirectUrl: "https://example.com/redirect",
customRedirectFailureUrl: "https://example.com/failure-redirect",
providerCategory: Seam.Api.ConnectWebviews.CreateRequest.ProviderCategoryEnum.Stable,
waitForDeviceCreation: true
);
Console.WriteLine(createdConnectWebview);
Response:
{
"connect_webview_id": "382034e3-0568-4e56-a226-d77778913e27",
"url": "https://connect.getseam.com/connect_webviews/view?connect_webview_id=382034e3-0568-4e56-a226-d77778913e27&auth_token=9eBKNtzB6ZKkSPPD33MZFshYSbmBcSMz7",
"workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
"accepted_providers": [
"august",
"avigilon_alta",
"brivo",
"schlage",
"smartthings",
"yale",
"nuki",
"salto",
"controlbyweb",
"minut",
"my_2n",
"kwikset",
"ttlock",
"noiseaware",
"igloohome",
"ecobee",
"hubitat",
"four_suites",
"dormakaba_oracode",
"lockly",
"wyze"
],
"accepted_devices": [],
"created_at": "2023-11-15T23:34:13.279Z"
}
Request:
ConnectWebview createdConnectWebview = seam.connectWebviews().create(ConnectWebviewsCreateRequest.builder()
.customRedirectUrl("https://example.com/redirect")
.customRedirectFailureUrl("https://example.com/failure-redirect")
.providerCategory(ProviderCategory.STABLE)
.waitForDeviceCreation(true)
.build());
System.out.println(createdConnectWebview);
Response:
{
"connect_webview_id" : "945554d6-ab1f-4f82-9683-21003f547cd1",
"url" : "https://connect.getseam.com/connect_webviews/view?connect_webview_id=945554d6-ab1f-4f82-9683-21003f547cd1&auth_token=3ArqVmE7WzA4SWpMLypojEChSsvjPH5s9",
"workspace_id" : "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
"device_selection_mode" : "none",
"accepted_providers" : [ "august", "avigilon_alta", "brivo", "schlage", "smartthings", "yale", "nuki", "salto", "controlbyweb", "minut", "my_2n", "kwikset", "ttlock", "noiseaware", "igloohome", "ecobee", "hubitat", "four_suites", "dormakaba_oracode", "lockly", "wyze" ],
"any_provider_allowed" : false,
"any_device_allowed" : false,
"created_at" : "2023-11-15T23:39:34.136Z",
"login_successful" : false,
"status" : "pending",
"custom_redirect_url" : "https://example.com/redirect",
"wait_for_device_creation" : true,
"custom_redirect_failure_url" : "https://example.com/failure-redirect",
"automatically_manage_new_devices" : true,
"authorized_at" : null,
"custom_metadata" : { },
"selected_provider" : null
}
Store the
connect_webview_id
and url
for the created Connect Webview.You use the URL to redirect your app to the Connect Webview. You use the ID later to verify the success of the connection attempt.
Pass the Connect Webview
url
to the client portion of your app and redirect your app to this URL.The resulting page displays the authorization flow through which your app user can link their device account to Seam.

Once the user has completed the authorization flow, the Connect Webview redirects back to your app (specifically to the
custom_redirect_url
). Note that Seam appends the following search parameters to the URL after the redirect:connect_webview_id
- If there is an error,
error_code
anderror_message
Use one of the following methods to verify that your user successfully connected their account to Seam through your app:
- Polling: Use the
connect_webview_id
to retrieve the Connect Webview. Check thestatus
of the Connect Webview to see if it changed tosuccess
. - Webhook: Watch for a
connected_account.connected
event with aconnect_webview_id
that matches that of the Connect Webview that you created.
Once the connection has occurred successfully, the Connect Webview and the
connected_account.connected
event payload include a connected_account_id
.Use the
connected_account_id
to make requests for your user's account and devices. Note that if you set wait_for_device_creation
to false
for the Connect Webview, you should wait for the connected_account.completed_first_sync
event before retrieving the user's devices. This event indicates that Seam has finished the first sync of the connected account and the devices are now available.To incorporate a Connect Webview in your app using an HTML iframe, first create the Connect Webview. Display the URL for the created Connect Webview in an iframe. After your user has completed the Connect Webview, verify that your user has connected their device account successfully to Seam. Then, you can use the Seam API to control your users' connected devices.
When your user initiates an action in your app to connect their device account to Seam, create a Connect Webview (
connect_webview
object).We recommend setting
wait_for_device_creation
to true
so that the Connect Webview does not complete until Seam completes the first sync of the connected account and devices.Python
cURL (bash)
JavaScript
Ruby
C#
Java
Request:
created_connect_webview = seam.connect_webviews.create(
custom_redirect_url = "https://example.com/redirect",
custom_redirect_failure_url = "https://example.com/failure-redirect",
provider_category = "stable",
wait_for_device_creation = True
)
pprint(created_connect_webview)
Response:
ConnectWebview(workspace_id='398d80b7-3f96-47c2-b85a-6f8ba21d07be',
connect_webview_id='2c852289-ee42-49d0-bddc-0410b518003d',
status='pending',
url='https://connect.getseam.com/connect_webviews/view?connect_webview_id=2c852289-ee42-49d0-bddc-0410b518003d&auth_token=z7Wu2Lc85gYUbNUhdvCWaEhmQv61FziA',
login_successful=False,
device_selection_mode='none',
any_provider_allowed=False,
any_device_allowed=False,
created_at='2023-11-15T23:24:36.947Z',
custom_metadata={},
connected_account_id=None,
authorized_at=None,
custom_redirect_url='https://example.com/redirect',
custom_redirect_failure_url='https://example.com/failure-redirect',
accepted_providers=['august',
'avigilon_alta',
'brivo',
'schlage',
'smartthings',
'yale',
'nuki',
'salto',
'controlbyweb',
'minut',
'my_2n',
'kwikset',
'ttlock',
'noiseaware',
'igloohome',
'ecobee',
'hubitat',
'four_suites',
'dormakaba_oracode',
'lockly',
'wyze'],
accepted_devices=[],
selected_provider=None,
wait_for_device_creation=True,
automatically_manage_new_devices=True)
Request:
curl -X 'POST' \
'https://connect.getseam.com/connect_webviews/create' \
-H 'accept: application/json' \
-H 'Authorization: Bearer ${API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"custom_redirect_url": "https://example.com/redirect",
"custom_redirect_failure_url": "https://example.com/failure-redirect",
"provider_category": "stable",
"wait_for_device_creation": true
}'
Response:
{
"connect_webview": {
"url": "https://connect.getseam.com/connect_webviews/view?connect_webview_id=e386fe69-7bce-4796-bceb-44cc240fd604&auth_token=CvPDERYGGMvqgo6N1gsT7XRBieBtPqtUG",
"status": "pending",
"workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
"custom_metadata": {},
"accepted_devices": [],
"login_successful": false,
"selected_provider": null,
"accepted_providers": [
"august",
"avigilon_alta",
"brivo",
"schlage",
"smartthings",
"yale",
"nuki",
"salto",
"controlbyweb",
"minut",
"my_2n",
"kwikset",
"ttlock",
"noiseaware",
"igloohome",
"ecobee",
"hubitat",
"four_suites",
"dormakaba_oracode",
"lockly",
"wyze"
],
"any_device_allowed": false,
"connect_webview_id": "e386fe69-7bce-4796-bceb-44cc240fd604",
"custom_redirect_url": "https://example.com/redirect",
"any_provider_allowed": false,
"device_selection_mode": "none",
"wait_for_device_creation": true,
"custom_redirect_failure_url": "https://example.com/failure-redirect",
"automatically_manage_new_devices": true,
"created_at": "2023-11-15T23:25:47.222Z",
"authorized_at": null
},
"ok": true
}
Request:
const createdConnectWebview = await seam.connectWebviews.create({
custom_redirect_url: "https://example.com/redirect",
custom_redirect_failure_url: "https://example.com/failure-redirect",
provider_category: "stable",
wait_for_device_creation: true
})
console.log(createdConnectWebview)
Response:
{
url: 'https://connect.getseam.com/connect_webviews/view?connect_webview_id=28fa1da1-d4ab-454c-a622-3ca95f22028a&auth_token=2r2Rn8V5QUtxE79gNhTmTK58KkuqrwU8d',
status: 'pending',
workspace_id: '398d80b7-3f96-47c2-b85a-6f8ba21d07be',
custom_metadata: {},
accepted_devices: [],
login_successful: false,
selected_provider: null,
accepted_providers: [
'august', 'avigilon_alta',
'brivo', 'schlage',
'smartthings', 'yale',
'nuki', 'salto',
'controlbyweb', 'minut',
'my_2n', 'kwikset',
'ttlock', 'noiseaware',
'igloohome', 'ecobee',
'hubitat', 'four_suites',
'dormakaba_oracode', 'lockly',
'wyze'
],
any_device_allowed: false,
connect_webview_id: '28fa1da1-d4ab-454c-a622-3ca95f22028a',
custom_redirect_url: 'https://example.com/redirect',
any_provider_allowed: false,
device_selection_mode: 'none',
wait_for_device_creation: true,
custom_redirect_failure_url: 'https://example.com/failure-redirect',
automatically_manage_new_devices: true,
created_at: '2023-11-15T23:28:03.845Z',
authorized_at: null
}
Request:
created_connect_webview = client.connect_webviews.create(
custom_redirect_url: "https://example.com/redirect",
custom_redirect_failure_url: "https://example.com/failure-redirect",
provider_category: "stable",
wait_for_device_creation: true
)
puts created_connect_webview.inspect
Response:
<Seam::ConnectWebview:0x00438
url="https://connect.getseam.com/connect_webviews/view?connect_webview_id=c1350df4-278f-42cc-9c16-4f9e41103796&auth_token=6zrib4wrGZMDxvJxPQQFiB6snmx7UAU6E"
status="pending"
workspace_id="398d80b7-3f96-47c2-b85a-6f8ba21d07be"
custom_metadata={}
accepted_devices=[]
login_successful=false
selected_provider=nil
accepted_providers=["august", "avigilon_alta", "brivo", "schlage", "smartthings", "yale", "nuki", "salto", "controlbyweb", "minut", "my_2n", "kwikset", "ttlock", "noiseaware", "igloohome", "ecobee", "hubitat", "four_suites", "dormakaba_oracode", "lockly", "wyze"]
any_device_allowed=false
connect_webview_id="c1350df4-278f-42cc-9c16-4f9e41103796"
custom_redirect_url="https://example.com/redirect"
any_provider_allowed=false
device_selection_mode="none"
wait_for_device_creation=true
custom_redirect_failure_url="https://example.com/failure-redirect"
automatically_manage_new_devices=true
created_at=2023-11-15 23:31:12.082 UTC>
Request:
var createdConnectWebview = seam.ConnectWebviews.Create(
customRedirectUrl: "https://example.com/redirect",
customRedirectFailureUrl: "https://example.com/failure-redirect",
providerCategory: Seam.Api.ConnectWebviews.CreateRequest.ProviderCategoryEnum.Stable,
waitForDeviceCreation: true
);
Console.WriteLine(createdConnectWebview);
Response:
{
"connect_webview_id": "382034e3-0568-4e56-a226-d77778913e27",
"url": "https://connect.getseam.com/connect_webviews/view?connect_webview_id=382034e3-0568-4e56-a226-d77778913e27&auth_token=9eBKNtzB6ZKkSPPD33MZFshYSbmBcSMz7",
"workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
"accepted_providers": [
"august",
"avigilon_alta",
"brivo",
"schlage",
"smartthings",
"yale",
"nuki",
"salto",
"controlbyweb",
"minut",
"my_2n",
"kwikset",
"ttlock",
"noiseaware",
"igloohome",
"ecobee",
"hubitat",
"four_suites",
"dormakaba_oracode",
"lockly",
"wyze"
],
"accepted_devices": [],
"created_at": "2023-11-15T23:34:13.279Z"
}
Request:
ConnectWebview createdConnectWebview = seam.connectWebviews().create(ConnectWebviewsCreateRequest.builder()
.customRedirectUrl("https://example.com/redirect")
.customRedirectFailureUrl("https://example.com/failure-redirect")
.providerCategory(ProviderCategory.STABLE)
.waitForDeviceCreation(true)
.build());
System.out.println(createdConnectWebview);
Response:
{
"connect_webview_id" : "945554d6-ab1f-4f82-9683-21003f547cd1",
"url" : "https://connect.getseam.com/connect_webviews/view?connect_webview_id=945554d6-ab1f-4f82-9683-21003f547cd1&auth_token=3ArqVmE7WzA4SWpMLypojEChSsvjPH5s9",
"workspace_id" : "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
"device_selection_mode" : "none",
"accepted_providers" : [ "august", "avigilon_alta", "brivo", "schlage", "smartthings", "yale", "nuki", "salto", "controlbyweb", "minut", "my_2n", "kwikset", "ttlock", "noiseaware", "igloohome", "ecobee", "hubitat", "four_suites", "dormakaba_oracode", "lockly", "wyze" ],
"any_provider_allowed" : false,
"any_device_allowed" : false,
"created_at" : "2023-11-15T23:39:34.136Z",
"login_successful" : false,
"status" : "pending",
"custom_redirect_url" : "https://example.com/redirect",
"wait_for_device_creation" : true,
"custom_redirect_failure_url" : "https://example.com/failure-redirect",
"automatically_manage_new_devices" : true,
"authorized_at" : null,
"custom_metadata" : { },
"selected_provider" : null
}
Store the
connect_webview_id
and url
for the created Connect Webview.You use the URL to display the Connect Webview in an iframe. You use the ID later to verify the success of the connection attempt.
Pass the Connect Webview
url
to the client portion of your app and use an HTML iframe to display the Connect Webview URL.For example:
<iframe style="border: none;min-height: 600px;height: 100%;width: 100%"
src="<your connect_webview.url>"
/>
Use one of the following methods to verify that your user successfully connected their account to Seam through your app:
- Polling: Use the
connect_webview_id
to retrieve the Connect Webview. Check thestatus
of the Connect Webview to see if it changed tosuccess
. - Webhook: Watch for a
connected_account.connected
event with aconnect_webview_id
that matches that of the Connect Webview that you created. - Event listening: When you host a Connect Webview in an 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 formessage
events.For example:window.addEventListener("message",(event) => {if (event.data?.event?.event_type === "webview.login_successful") {// Do something.}},false);When the device account connection occurs successfully, the Connect Webview issues awebview.login_successful
event. This event includes theconnect_webview_id
. If the device account connection fails, the Connect Webview issues awebview.login_failed
event. If there is an error, this event also includes theerror_code
anderror_message
. For example:{"event": {"event_type": "webview.login_successful","connect_webview_id": "123e4567-e89b-12d3-a456-426614174000"}}
Once the connection has occurred successfully, the Connect Webview and the
connected_account.connected
event payload include a connected_account_id
.Use the
connected_account_id
to make requests for your user's account and devices.
Note that if you set wait_for_device_creation
to false
for the Connect Webview, you should wait for the connected_account.completed_first_sync
event before retrieving the user's devices. This event indicates that Seam has finished the first sync of the connected account and the devices are now available.