Mobile App Integration

Platforms who want to use Chatbot in their iOS or Android app can integrate using Webview. Instead of passing Chatbot configurations via a client-side Javascript call, Webview integration passes those configurations via query string. Communication between the mobile app and the Webview is handled by HTTP redirects.

The initialization URL is optimized for WebViews:

Project	Production Link	Sandbox Link
Router	https://uiaas-v2.synapsefi.com/chatbot-router	https://uat-uiaas-v2.synapsefi.com/chatbot-router
Interchange	https://uiaas-v2.synapsefi.com/chatbot-interchange	https://uat-uiaas-v2.synapsefi.com/chatbot-interchange
Bank Logins	https://uiaas-v2.synapsefi.com/synapse-chatbot	https://uat-uiaas-v2.synapsefi.com/synapse-chatbot
Card Management	https://uiaas-v2.synapsefi.com/chatbot-cards	https://uat-uiaas-v2.synapsefi.com/chatbot-cards

During Chatbot configuration, you must pass a URL-encoded JSON object with the following URL parameters:

Parameter	Description	Supported Project
`defaultPath`	[Required] 'Router' For Chatbot Router 'CARDS' For Card Management 'BANK_LOGINS' For Linking Bank Credentials 'INTERCHANGE' For Linking/Unlinking Cards	Bank Logins, Interchange, Card Management, Router
`env`	[Required] The Synapse API environment on which to create user accounts. For development use `UAT`, and use `production` for Production.	Bank Logins, Interchange, Card Management, Router
`publicKey`	[Required] A valid public key	Bank Logins, Interchange, Card Management, Router
`fp`	[Required] A valid device fingerprint. See Register New Fingerprint API.	Bank Logins, Interchange, Card Management, Router
`userId`	[Required] The ID of the user	Bank Logins, Interchange, Card Management, Router
`isWebView`	[Required] true	Bank Logins, Interchange, Card Management, Router
`institution`	[Optional] This will skip the Step[selectBank] step and go straight to Step[sendCredential] based on the [bank_code] passed. Eg, ‘bofa’.	Bank Logins

Below is an example of how clients might generate the link to put in the Webview.

https://(uat-)uiaas-v2.synapsefi.com/chatbot-router //selected project url
?publicKey=[SYNAPSE_PUBLIC_KEY]
&fp=[SYNAPSE_USER_FINGERPRINT]
&userId=[SYNAPSE_USER_ID]
&isWebView=true
&defaultPath=ROUTER
&env=UAT

To communicate between Chatbot Bank Logins and your app, we have similar functions as we have for desktop integration. Instead of calling as a javascript callback function, the event type is communicated via the URL host and data is passed via the query string.

Exit event

The exit event is similar to the onExit callback and is sent when the user exits the chatbot. The following information is available from the query string:

Parameter	Description	Supported Project
`userId`	ID of the user	Bank Logins, Interchange, Card Management
`step_name`	This indicates the point at which the user exited the chatbot	Bank Logins, Interchange, Card Management
`type`	Type of this event	Bank Logins, Interchange, Card Management

The following information is available from the query string as an example:

Success event

The success event is similar to the onSuccess callback and is sent when the user successfully linked the bank accounts through the chatbot. The following information is available from the query string:

Parameter	Description	Supported Project
`userId`	Id of the user	Bank Logins, Interchange, Card Management
`step_name`	This indicates the point at which the user successfully made an action	Bank Logins, Interchange, Card Management
`type`	Type of this event	Bank Logins, Interchange, Card Management
`linkedNode`	A list of `nodes_id` strings	Bank Logins, Interchange
`unlinkedNode`	A list of `nodes_id` strings	Interchange
`institution_name`	The full institution name (e.g. "Bank of America")	Bank Logins
`card`	Card information (status) if it was modified	Card Management

Error event

The error event is similar to the onError callback and is sent when the user faced the error when using chatbot. The following information is available from the querystring:

Parameter	Description	Supported Project
`userId`	ID of the user	Bank Logins, Interchange, Card Management
`error_code`	The error code that the user encountered, see Common Errors	Bank Logins, Interchange, Card Management
`http_code`	The http code of error that the user encountered, see Common Errors	Bank Logins, Interchange, Card Management
`error_message`	The error message that the user encountered	Bank Logins, Interchange, Card Management
`time`	The timestamp when the error happened	Bank Logins, Interchange, Card Management
`step_name`	This indicates the point at which the user encountered the error	Bank Logins, Interchange, Card Management
`type`	Type of this event	Bank Logins, Interchange, Card Management
`institution_name`	The full institution name (e.g. "Bank of America")	Bank Logins, Interchange, Card Management

chatbot://exit
?userId=’string’
&step_name= ‘string’,
&type=’exit’

chatbot://success
?userId=’string’
&step_name= ‘string’
&type=’success’
&linkedNode=’node_id_string1’, ’node_id_string2’ (if more than one node)
&unlinkedNode=’node_id_string1’, ’node_id_string2’ (if more than one node)
&institution_name=’string’
&card=’string’

chatbot://error
?userId=’string’
&step_name= ‘string’
&type= “error”
&error_code=  ‘string’
&http_code= ‘string’
&error_message= ‘string’
&institution_name=’string’
&time=”string”

WebView examples

To get your Link WebView integration started, check out our example apps, available for iOS.
Example app is runnable (on both simulators and devices) and includes code to initialize Link and process events sent from Link to your app via HTTP redirects.