This integration allows you to leverage Voyado's unified customer data (CDP) and loyalty insights within Tweakwise to personalize lister pages and product recommendations. By connecting these platforms, you can transform customer behavior and "Target Audiences" captured in Voyado into targeted merchandising strategies.

Unlike some platforms that only store raw event logs, Voyado offers calculated insights (like AI-driven product recommendations and Target Audiences) which can be directly utilized.

Voyado on the lister page

You can use Voyado to personalize lister pages via the Tweakwise External Data Component. This component requests a list of product IDs specific to the user directly from Voyado's recommendation engine.

• Process: Voyado has a dedicated endpoint that returns AI-driven product recommendations based on a customer's purchase history and behavior.
• Technical setup: Configure the Tweakwise External Data Component to call the Voyado API endpoint using the current user's contactId. Tweakwise will receive the list of SKUs and hydrate them on designated positions in the builder to display the lister page.

Endpoint Configuration: Use the following Voyado API V3 endpoint:
GET /api/v3/contacts/{contactId}/productrecommendations

Response example:

Voyado in recommendations

While you can fetch a raw list of products from Voyado (as shown above), doing so for standard recommendation widgets can bypass the Tweakwise rule engine. To get the "best of both worlds," we recommend using Voyado Target Audiences or Labels to trigger specific Tweakwise strategies.

The Strategy:

• Configure in Tweakwise: Create a recommendation group with a specific key for each Voyado audience (e.g., GroupKey = audience-loyal-members).
• Retrieve Audience: On the platform side, fetch the current user's profile from Voyado to see which Target Audiences they belong to.
• Request Recommendation: Call the Tweakwise Recommendations API using the mapped audience name as the GroupKey.
• Fallback: Always configure a generic recommendation (e.g., "Trending") if the user does not belong to a specific audience.

This method uses Voyado for customer intelligence (segmentation) while letting Tweakwise handle the specific sorting, stock logic, and boosting rules.

Retrieving Customer Audiences

To find a customer's audiences or segments, you generally retrieve the contact profile.

• Step 1: Get Contact Data: Call GET /api/v3/contacts/{contactId} (or lookup by email if the ID is unknown).
• Step 2: Identify Audiences: Parse the response to find the targetAudiences or labels array.
• Step 3: Map to Tweakwise: Use the audience ID or Name to determine which Tweakwise GroupKey to request.

Example

Imagine a fashion webshop. Here is how we apply this when a user visits the home page:

1. The user logs in, and your middleware identifies their Voyado Contact ID.
2. Your system checks Voyado and sees the user is in the "High Spender / VIP" Target Audience.
3. Your system maps this audience to the recommendation groupkey segment-winter-luxury.
4. The website calls Tweakwise:
   /recommendations/{instancekey}/{productid}/segment-winter-luxury
5. Tweakwise only shows products from the "Coats" category with a price > €200, applying the merchandising rules that are configured in Tweakwise.

Important Considerations

• Authentication: Voyado API calls require an API key, typically sent in the x-api-key header. Ensure your External Data Component or middleware is configured to send this securely.
• Latency: The "Lister Page" implementation relies on a real-time call to Voyado. Ensure your Voyado instance and middleware are performant to strictly limit page load delays.
• Contact ID Availability: To use these features, the user must be identified (logged in) or you must have a valid contactId stored in a cookie/session.
• Fallback Logic: If the productrecommendations endpoint returns an empty list or errors out (e.g., for a new user with no history), ensure Tweakwise falls back to a default sorting algorithm or recommendation set.

Frequently Asked Questions

Can I use the product recommendations endpoint for the "Recommendations" widget as well? Yes, you can. However, using the "Target Audience" strategy allows you to use Tweakwise's visual merchandising rules (like filtering out sale items or boosting specific brands) on top of the user segmentation. Using the endpoint directly gives you exactly what Voyado suggests, without Tweakwise's filtering capabilities.

How does the External Data Component handle the SKUs? Tweakwise receives the list of SKUs (e.g., ["1234", "5678"]) and matches them against product data we receive. It then renders the products in the order provided by Voyado on the positions in the builder you have configured.