The withDeliveryContentItem helper

The handlebars helper: {{withDeliveryContentItem}} can be used within the custom payload to get content from the delivery API. This allows you to supplement the information that is provided in the standard payload for a webhook event. This is particularly useful for retrieving linked content, for example. You can also use the helper to filter content by locale.

Parameters

withDeliveryContentItem takes up to 6 {string} parameters:

  • contentItemId : the id of the content item to retrieve
  • account: the Amplience account name (for example: ampproduct)

Optional parameters

  • stagingEnvironment: The virtual staging domain to use to retrieve unpublished content (optional)
  • locale: Return content for the specified locale (optional). This is used with field level localized content. Specifying locale is particularly useful when used with Amplience Search. See locale for more details.
  • snapshotId: the exact snapshot to retrieve (optional - only for snapshot payloads).
  • mediaHost: override the hostname used when constructing media URLs (optional). If not supplied, the hostname defaults to cdn.media.amplience.net, or the mediaHost configured for your account). See mediaHost for more details.
Adding a custom payload using the withdeliverycontentitem helper.
Adding a custom payload using the withdeliverycontentitem helper.

Mediahost

withDeliveryContentItem will return media (such as images and video) with Amplience's default production media domain of cdn.media.amplience.net, rather than a virtual staging domain. This is to ensure that you do not retrieve media from virtual staging domains in your production code. However, your media must be published.

If you do want to index staged media URLs, then include mediaHost="myVseUrl" as an additional parameter, where myVseUrl is replaced with your staging environment. Note that staged media URLs must not be used in Production. This setting can also be used to replace cdn.media.amplience.net if you have a custom media domain.

Locale

If you are using field level localization, then you can retrieve the full localized content for all locales, or filter it by a specific locale using the locale parameter.

Filtering content by locale within your custom payload is particularly useful when used together with Amplience Search. See the Search and localization page for more details.

The following custom payload uses withDeliveryContentItem to retrieve content for the fr-FR locale.

{{#withDeliveryContentItem contentItemId=payload.rootContentItem.id account="ampproduct" stagingEnvironment="kuifkfmrgfsv1qjsmei8dbbnq.staging.bigcontent.io" locale="fr-FR}}
{{{JSONstringify .}}}
{{/withDeliveryContentItem}}

Locale filtering rules

The withDeliveryContentItem helper is just a wrapper around the Content Delivery API and so locale filtering rules work in the same way.

  • An exact match such as locale=fr-FR or locale=de-DE will return content for the chosen locale
  • locale=* will return content for the first locale that contains a value
  • locale=en-* will return content for the first locale that has "en" as a language code
  • You can specify multiple locales separated by a comma and these will be evaluated from left to right until a matching locale is found. For example, locale=fr-BE,en-GB will first look for content for the fr-BE locale and if none is available will look for content with the en-GB locale.

If a locale cannot be found for a localized property then that property value will be set to null.

For more information about locales, see the localization overview section.

Example- the entire payload

The following example shows how to use JSONstringify to output the entire content item into the custom payload. This is useful during development as a starting point to help you tailor your handlebars.

{{#withDeliveryContentItem contentItemId=payload.rootContentItem.id account="ampproduct" stagingEnvironment="kuifkfmrgfsv1qjsmei8dbbnq.staging.bigcontent.io" snapshotId=payload.id}}
{{{JSONstringify .}}}
{{/withDeliveryContentItem}}

The following is shown in the webhook details window. The body section of the webhook request contains the entire content item and the custom payload is also shown.

The body section of the request is generated from the custom payload.
The body section of the request is generated from the custom payload.

Webhooks overview

Webhooks standard payloads

Handlebars helpers

Search and localization

Virtual staging in Dynamic Content

Examples

Slack example Part 1- Content created and updated

Slack example Part 2- Assigning content

Search example Part 1

Search example Part 2

Search example Part 3