Skip to main content
Qwilr API

Tokens deepdive

Tokens are how you pass data into your page. We'll explain the variety of ways you can use them.

Token data-type and rendering

Tokens are strings. There are no strong-typing of tokens, meaning things like date formats, or number formats coming from a token need to be passed through as the final string you would like to display.

Good

{
  ...
  substitutions: {
    numContacts: "3",
    date: "Feb 4 2021"
  }
}

Bad

{
  ...
  substitutions: {
    numContacts: 3,
    date: 1612403569314
  }
}

Available Token placements

Tokens can be placed in:

  • Text areas within the Text block
    • Including within table cells
    • Including within a 2 column layout
  • Text area within the Splash Block, Video Block, Embed Block, Quote Block, and Accept block

Tokens cannot be placed in:

  • Any configuration areas for blocks, for example
    • Foldable block button text (default text is "show/hide")
    • Custom Accept text for the Accept block
    • Custom forms for the Accept block
  • Within the Quote line-items of a Quote
  • The Accept button itself

All Tokens are optional, and null values are inserted as empty strings. This means that if, for example, a bullet point has only a token placeholder, the bullet point will always be there.

Custom Tokens

With the Qwilr API, you're able to specify and deliver any token name you like. These are "Custom Tokens." You can manage which custom tokens you're using with our GUI.

Tokens for images

Tokens can be used for placing media within text areas. The inline image widget expects a string for the path of the image or video, either owned by you, or uploaded to our image library.

Your responsibilities:

It's up to you to ensure the accuracy of the image path.

It's up to you to ensure the image is publicly available to the internet, so that people viewing your page can see the image.

Tokens for videos

Tokens can be used to determine which video is loaded into a video embed.

Your responsibilities:

It's up to you to ensure your video is on a supported video service - YouTube, Brightcove, or Loom - and that this video is publicly available to the internet, so that people viewing your page can see the video.

For Youtube, Brightcove, Wistia, and Brightcove, the video token expects the URL seen in the embed code provided by the platform, not the entire blob of embed HTML.

Vimeo not supported: Vimeo do not provide embed code that includes a usable URL, so it's not currently possible to use Vimeo videos with custom tokens.

Tokens for maps

Tokens can be used to control the focus of the map widget. Using "Share" and Embed option in Google Maps, copy the URL from within the embed HTML. This URL will be what the map widget expects to receive.

Repeating Tokens

Repeating Tokens allow the rendering of an array of objects with string properties. This results in templated set of content to repeat within a block.

In this example we are rendering a repeating token for "contacts" within a text block. Based on the sub-tokens of the Repeating Token we are able to allow a variable number of repeats matching the data input.

Repeating content with tokens in the editor, and the output result showing a list of contacts

Repeating tokens are the parent token. Within a repeating section of content, you can reference one Repeating Token, and any project level tokens

Note on CRM Tokens

CRM tokens automatically map existing data in a CRM to tokens in Qwilr. They're intended to be used when creating a page from within a CRM like SalesForce. CRM tokens are created at the time of connecting a CRM integration to Qwilr. These tokens are generated based on the standard schemas of data held in the CRM you've connected to - Salesforce or HubSpot. These are not used with the Qwilrs API use cases, since the integrations themselves power the page creation from within each CRM platforms.