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.

• ESP integration
  Messages are pushed directly to a compatible Email Service Provider via a standardised HTTP API.

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 it for email delivery and want Product Agent messages to respect existing consent rules and sending preferences. Templates and branding stay inside Klaviyo.

Webhook integration¶

Use webhooks if you want full control over delivery, rendering, and retries — for example when routing messages into a custom ESP or internal system.

ESP integration¶

Use the ESP integration if you are an Email Service Provider building a native Hello Retail integration. Hello Retail pushes messages to your platform via a standardised HTTP API, and your platform handles delivery.

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:

• Using Product Agents with Klaviyo

  For event-based delivery via Klaviyo flows.

• Using Product Agents with webhooks

  For direct HTTP-based delivery.

• ESP Integration Guide

  For ESPs integrating directly with Hello Retail via a standardised HTTP API.