Skip to content

Product Agents – Integration Overview

Product Agents generate automated, product-aware messages based on customer behavior and product data.

This guide explains how Product Agents integrate with external systems, what they emit, and how delivery responsibilities are split between Hello Retail and your chosen channel.

It is intended for developers, agencies, and technical partners implementing Product Agents.

What Product Agents emit

Product Agents do not send emails directly to customers.

Instead, they:

  • Evaluate product and customer signals
  • Decide what message should be sent and when
  • Generate a message payload
  • Send that payload to a configured delivery channel

The delivery channel is responsible for final message delivery.

Supported delivery channels

Product Agents currently support the following delivery channels:

  • Klaviyo
    Messages are sent as custom events and consumed by a Klaviyo flow.

  • Webhooks
    Messages are delivered as HTTP payloads to a customer-defined endpoint.

Each channel receives the same logical message data, but the transport and consumption model differs.

Choosing the right integration

Klaviyo integration

Use Klaviyo if:

  • You already use Klaviyo for email delivery
  • You want Product Agent messages to respect existing consent and sending rules
  • You prefer configuring templates and logic inside Klaviyo

In this setup:

  • Product Agents emit a custom event
  • Klaviyo controls email delivery
  • Templates and branding live in Klaviyo

Webhook integration

Use webhooks if:

  • You want to handle message delivery yourself
  • You need to integrate with a non-Klaviyo ESP
  • You want full control over how messages are processed

In this setup:

  • Product Agents send a structured payload
  • Your system is responsible for delivery, retries, and rendering

What Product Agents are responsible for

Product Agents handle:

  • Trigger detection
  • Eligibility evaluation
  • Scheduling and postponement
  • Message selection and prioritisation
  • Cancellation when conditions change

Product Agents ensure that:

  • Messages are relevant
  • Messages are not duplicated
  • Messages respect global frequency rules

What delivery channels are responsible for

Delivery channels handle:

  • Consent enforcement
  • Suppression rules
  • Throttling and smart sending
  • Rendering templates
  • Final delivery success or failure

This separation allows Product Agents to remain channel-agnostic.

Scheduling vs delivery

It is important to distinguish between scheduling and delivery.

  • Scheduling is decided by Product Agents
    When a message should be sent, postponed, or canceled.

  • Delivery is decided by the channel
    Whether a message is actually delivered to the recipient.

A message may be:

  • Scheduled but never sent
  • Sent to the channel but blocked there
  • Sent and delivered successfully

All three are valid and expected outcomes.

Message lifecycle (high level)

A Product Agent message typically moves through these states:

  1. Trigger detected
  2. Message evaluated
  3. Message scheduled
  4. Message sent to channel
  5. Message delivered or blocked by channel

Not all messages reach the final step.

Usage of image scaling

In product agent messages product images will be available in a scalable version. Given a product the url for the scalable image is available in product.image.scalableUrl.

Using the scalable url will just serve the original image through the Hello Retail CDN. You can append scaling parameters to get resized versions of the image. The format is as follows:

{scalableUrl}/{resizeType}:{width}:{height}.{extension}

Resize types

  • auto - Automatically choose best resize type
  • fit - Resize to fit within dimensions, preserving aspect ratio
  • fill - Resize to fill dimensions exactly, cropping if needed (uses smart gravity)
  • fill-down - Like fill, but only downscales
  • force - Resize to exact dimensions, ignoring aspect ratio

Width and height

Specify the size of image you want. Both width and height are limited to 2048 pixels.

Extension (optional)

jpg, jpeg, png, webp, avif, gif

When omitted, format is auto-selected based on the browser's Accept header (typically WebP or AVIF for modern browsers).

Example usage

When used within a typical email template usage will look like this:

<html>
    <body>
    <h1>{product.title}</h1>
    <img src="{product.image.scalableUrl}/auto:400:400.jpg" width="200" height="200">
    </body>
</html>

Next steps

Once you understand the integration model, continue with one of the following guides: