Create Dynamic Cards with info from an external source

This is an advanced type of Cards, where Cards are created based on information from an external source. Unlike Generic Cards, you don’t need to manually add data to the different Cards. In this case, what is needed is a URL where the Module can retrieve the Cards in the format specified below.

In this article, we will address:

How to create Dynamic Cards

To use this functionality, open a Module's message, click "Add Cards", and choose “Dynamic Cards”.

How-to-add-dynamic-cards-BotXO.pngAn input field will then appear where you will add the URL of the service that will return the Cards.

How-to-add-url-in-dynamic-cards-BotXO.pngThe URL accepts Custom Variables. In this way, you can add parameters in the form of query strings or Dynamic URLs. For example, with query strings it would look like this:

http://someurl.site/this/is/a/path?query1=[customVariablekey=query1]&query2[customVariable key=query2]

If no Custom Variables are added, then the URL can be used to return random Cards every time it is hit. During the conversation, the Cards returned by the external service are dynamically generated, so different Cards will be shown.

Dynamic Cards JSON structure

This is the data structure that the external service must return in order to make Dynamic Cards work. It is composed of an array of one or more objects with the following parts:

  • Title: The title of the Card
  • Subtitle: The subtitle which goes just below the title in the Card
  • Is_shareable: A boolean indicating if the Card can be shared
  • Image_source_url: The URL of the image to be shown in the Card
  • Image_destination_url: The URL to be forwarded to when the Card image is clicked
  • Buttons: A list of objects that represent buttons in the Cards

An example of this structure in JSON is as follows:

[{  
  "title":"Card Title",
  "subtitle":"Card subtitle",
  "is_shareable":false,
  "image_destination_url":"http://web.site/to/forward/user/",
  "image_source_url":"https://www.web.site/with/img.jpg",
  "buttons":[]
}]

The number of buttons on the Cards is limited to three. If you add more than three buttons, only the first three buttons will be taken into account. Functionality for the buttons can be of the following types:

  • Send Message: When clicked, it sends a message to the bot, just like a Suggested Reply
  • Webview: When clicked, the webchat opens a webview with the content of the URL
  • Go To: In this case, a new tab is opened in the browser pointing to the URL

All buttons share the same properties:

  • Title: The button’s title
  • Is_active: Should always be true
  • Type: Indicates the button type
  • Options: Different for each button type

Below, you can view examples of scripts for each type of button:

Webview script

{  
	"title":"Webview",
	"is_active":true,
	"options":{  
	   "url":"http://www.website.com",
	   "window_size":"full"  # Options are: full, tall, compact
	},
	"type":"web_url"
}

Send Message script

{  
	"title":"Send message",
	"is_active":true,
	"type":"postback",
	"options":{  
	   "message":"This is a message"
	}
}

Go To script

{  
	"title":"Go to",
	"is_active":true,
	"type":"web_url_tab",
	"options":{  
	   "newtab_url":"http://www.google.es"
	}
}

All three button types script

[
   {
	  "image_source_url":"http://www.site/with/an/image.jpg",
	  "title":"Title",
	  "subtitle":"Subtitle",
	  "image_destination_url":"http://www.site/to/foward/user",
	  "is_shareable":false,
	  "buttons":[
		 {
			"options":{
			   "message":"This is a message"
			},
			"is_active":true,
			"type":"postback",
			"title":"Button 1 label"
		 },
		 {
			"options":{
			   "url":"http://www.google.es",
			   "window_size":"tall"
			},
			"is_active":true,
			"type":"web_url",
			"title":"Button 2 label"
		 },
		 {
			"options":{
			   "newtab_url":"http://www.google.es"
			},
			"is_active":true,
			"type":"web_url_tab",
			"title":"Button 3 label"
		 }
	  ]
   }
] 

Use Dynamic Cards in conjunction with Webhooks

If you are using a Webhook that stores the result of a search in a Custom Variable, you are able to render this result as Cards in a Bot Message.

The image below displays the "zendeskResultsCards" Custom Variable, which is generated from the <wh>Zendesk Guide Search Knowledge Base: Show as Cards Webhook Template. Upon firing the Webhook, this Custom Variable will be populated with data from the search query.

screenshot-me.botxo.co-2020.05.17-12_58_05.png

After the Webhook has been fired, we are able to render this response as Cards by inserting the following code into a bot message:

[customVariable key=zendeskResultsCards type=carrousel fallback="sample text"]

After the code has been implemented, the Cards will be rendered as shown here:

screenshot-me.botxo.co-2020.05.17-13_04_39.png

Create Dynamic Cards in Jinja2 templates

To eliminate the need for third-party APIs, you can generate Cards directly in Jinja2 templates. An example of this process is below.

First, the flow is created with the <md>Offer Cards – Set Variable and <md>Yes – Display Cards Modules.

cardsjinjamodules.jpg

In the “Connections” tab of the <md>Offer Cards – Set Variable Module, we set the variable “card” with value “jinja2 template” using the "All three button types script" shown above.

cardsjinjamodulesv.jpg

Then, in the <md>Yes – Display Cards Module, we enter the code [customVariable key=card type=carrousel fallback="sample text"].

cardsjinjadisplay1.jpg

This is what the flow looks like when tested:

cardsjinjatest.jpg

Was this article helpful?

0 out of 0 found this helpful
Have more questions? Submit a request

Comments (0 comments)

Please sign in to leave a comment.