Zipwhip Widget Authentication
When using the Widget to send messages, the user must be logged in to Zipwhip. By default, Zipwhip handles this automatically but you may also control the authentication using a session key or SSO connection.
Automatic
When a user loads the Widget, they will be automatically prompted to login if they are not already logged in. Once logged in, a cookie associated with the logged in Zipwhip user (called a session key) will be stored in the browser and used to automatically login to Zipwhip from that point forward.
Zipwhip session keys do not expire. Therefore, once a user logs in to Zipwhip and the session key is stored as a cookie in their browser, they will not be prompted to login to Zipwhip in that browser again. If the user wishes to logout of Zipwhip or to login to a different Zipwhip account, they must manually logout of Zipwhip or clear the session cookie from their browser.
Session Key
Zipwhip’s automatic login (as described above) works well in an evironment where each user has their own computer. But if you are in an environment where multiple users are sharing a computer you may want to manage authentication so that each user in your system is mapped to a specific Zipwhip account.
For example, lets say you have multiple users sharing a computer at the front desk of a health club, and each of those users must login to a unique account in your health club membership app when they begin a shift. When a user logs in to your membership app, you can automatically map that user to a specific Zipwhip account using a session key.
In order to map each unique user in your app to a unique user in Zipwhip, you would need to create a login form in your app that prompts each user to enter their Zipwhip username and password using the User Login API. You would only need to do this once.
The API request will result in a session key in the response from the server. You could then store the session key in your database and associate it with the logged in user of your app. For example:
| User in your app | Zipwhip Session Key |
|---|---|
| User A | d4c68682-95df-41c9-a268-5a54e3b6ccd6:377265507 |
| User B | e5c68682-95df-41c9-a268-5a54e3b7dcd6:377432508 |
| User C | c3c68682-95df-41c9-a268-5a54e3b8acd6:378965509 |
Once you’ve captured the Zipwhip session key for each user in your system, you will be able to automatically log them into the appropriate Zipwhip account when loading the Widget. You do this by changing the base path of the deeplink from this:
https://embed.zipwhip.com/
to this:
https://embed.zipwhip.com/v2/deeplink/{{sessionKey}}?path=/
and then appending the rest of the path (e.g. messaging/1234567890) to the url. The complete URL would look something like this:
https://embed.zipwhip.com/v2/deeplink/{{sessionKey}}?path=/messaging/1234567890
When you include the session key in the Widget src URL, as described above, it is equivalent to logging any previous users out and logging the new user in to the appropriate Zipwhip account.
SSO
If you are an enterprise customer using Single Sign On (SSO) to login to Zipwhip, you can automatically map users who are logged into your identity provider to the appropriate corresponding user account in Zipwhip by appending a connection parameter to the path.
For example, you would change this:
https://embed.zipwhip.com/messaging/12334567890
to this:
https://embed.zipwhip.com/messaging/12334567890?connection=acme-corp
When you include the connection param in the Widget src URL as described above, it is equivalent to logging any previous users out and logging the new user in to the appropriate Zipwhip account using SSO.