Zipwhip Widget Paths and Parameters

To embed the Zipwhip Widget, create an iframe with a src URL of https://embed.zipwhip.com. That will render the Inbox Component showing all conversations.

<iframe src="https://embed.zipwhip.com/" width="400px" height="600px"></iframe>

If you want to render the Messaging Component that shows a specific conversation, create an iframe with a src url of https://embed.zipwhip.com/messaging/{phoneNumber} where {phoneNumber} is the phone number of the mobile user you are having a conversation with. For example, if you want to text the mobile number (503) 575-2449, create a src URL like this:

<iframe src="https://embed.zipwhip.com/messaging/5035752449" width="400px" height="600px"></iframe>

Global Parameters

Key Description
Base URL (required) The base path to https://embed.zipwhip.com is required. If no additoinal path parameters are provided it will render the Inbox.

https://embed.zipwhip.com
Authentication (required) The authentication method used for logging into Zipwhip. Options are:

  • Automatic (default) — Zipwhip will prompt the user to login the first time and store their credentials as a browser cookie. The user will be automatically logged in after that.
  • Session — You provide a session key that automatically logs the user into the appropriate Zipwhip account.
  • SSO (Enterprise customers only) — You provide your SSO connection name parameter to log the user into the appropriate Zipwhip account.
See Authentication for more info.

Conversation Component Parameters

Key Description
mobilePhone (required) The path to /messaging/{mobilePhone} for the mobile phone number you wish to send the message to. The mobile phone number must be formatted as a string, either as a 10-digit US phone number without any punctuation symbols or spaces (e.g. 20655512341), or in E.164 format containing a ‘+’ followed by the ‘country code’ followed by the ‘mobile phone number’ (e.g. +12065551234).

https://embed.zipwhip.com/messaging/5035752449

You can address the widget to multiple phone numbers as well. See Group Messages for more info.
Name (optional) You can include a name appended to the phone number in the src url, so that the contact’s name is displayed in the header instead of the phone number. This will also automatically add the contact to the Zipwhip Contacts list. The phone number must come first, followed by first name and last name separated by spaces. Note: The spaces in the URL must be URL encoded.

https://embed.zipwhip.com/messaging/5035752449%20Steve%20Smith
overwrite=true (optional) If a Name is included in the url, as in the example above, and a contact already exists in Zipwhip with that phone number, the contact name will not be overwritten. If you wish to force an update of the name in Zipwhip, you can set the overwrite=true parameter in the url.

https://embed.zipwhip.com/messaging/5035752449%20Steve%20Smith?overwrite=true
body (optional) You can include an optional body parameter in the URL to prepopulate the message body in the Zipwhip compose box before sending the message. You could use this parameter to pre-fill the body with metadata from your CRM, such as an account number or status message. For example, the URL /messaging/5035752449?body=Hello World will display the Messaging Window addressed to the specified phone number with the words “Hello World” inserted into the Zipwhip compose box. The message body can be edited further before clicking Send. Note: The spaces in the URL must be URL encoded by replacing each space character with %20. Example:

https://embed.zipwhip.com/messaging/5035752449?body=Hello%20World
Dynamic Fields (optional) Zipwhip provides the ability to insert Dynamic Fields into the body of the text message. For example, if you’d like to greet the recipient by their first name, you could prepopluate the message body with the [First Name] dynamic field. The following dynamic fields are supported:

  • [First Name]
  • [Last Name]
  • [Company]
  • [Job Title]
  • [Email]
  • [Address Line 1]
  • [Address Line 2]
  • [City]
  • [State]
  • [Postal Code]
  • [Country]
  • [Custom Field 1]
  • [Custom Field 2]
You may include one or more of the dynamic fields listed above into the body of the text message. You must include the square brackets [ ] around the Dynamic Field and URL encode any spaces. Example:

https://embed.zipwhip.com/messaging/5035752449?body=Hello%20[First%20Name]

The Inbox and Conversation Components contain header and footer elements. Each of these elements can be shown or hidden through the use of the following URL parameters.

Widget UI Elements

Key Description
settingsHeader Show or hide the Settings Header. Defaults to true. If set to false the entire header will be hidden, thereby hiding the settingsMenu and switchboard elements within it. To hide it:

https://embed.zipwhip.com?settingsHeader=false
settingsMenu Show or hide the Settings Menu. Defaults to true. To hide it:

https://embed.zipwhip.com?settingsMenu=false
switchboard Show or hide the Line Switchter. Defaults to true. To hide it:

https://embed.zipwhip.com?switchboard=false
contactHeader Show or hide the Contact Header in the Conversation Component. Defaults to true. If set to false the entire header will be hidden, thereby hiding the inbox nav element within it. To hide it:

https://embed.zipwhip.com/messaging/5035752449?contactHeader=false
inbox The Conversation Component displays a navigation control (<) on the Contact Header for access to the Inbox. Defaults to true. In some cases, you may want the Messaging Window to be locked to a specific conversation without providing access to the Inbox and other conversations. This can be achieved by hiding the navigation control to the Inbox by setting the inbox=false parameter in the url like so:

https://embed.zipwhip.com/messaging/5035752449?inbox=false
footer Show or hide the Footer. Defaults to false. To show it:

https://embed.zipwhip.com?footer=true

Group Messages

The Widget supports group messages with up to 100 recipients. A group message is similar to a BCC in that the recipients will not see any others in the To field and their response will only be sent to the originator of the group message. You can create a group message by including multiple phone numbers in the src url separated by commas:

https://embed.zipwhip.com/messaging/5035752449,2068163997

You can optionally include a name with each phone number:

https://embed.zipwhip.com/messaging/5035752449%20Steve%20Smith,2068163597%20Sally%20Jones

You can also include a message body to send canned text to a group of recipients:

https://embed.zipwhip.com/messaging/5035752449,2068163997?body=Hello%20World

And group message can contain a message body with dynamic fields that will be updated with specific information for each contact:

https://embed.zipwhip.com/messaging/5035752449%20Steve%20Smith,2068163597%20Sally%20Jones?body=Hello%20[First%20Name]