Messages and Parts

A message has a role (user or assistant) and a list of parts. Parts are the blocks your UI renders — text, an image the shopper sent, or product cards from a catalog tool.

What the shopper sends

User parts are text and image. You can send either, or both.

// Text
{
  role: "user",
  parts: [{ type: "text", text: "I need waterproof hiking boots for day hikes, under $200" }],
}

// Image search
{
  role: "user",
  parts: [{ type: "image", url: "https://…/photo.jpg" }],
}

// Text + image
{
  role: "user",
  parts: [
    { type: "text", text: "find boots like these" },
    { type: "image", url: "data:image/jpeg;base64,..." },
  ],
}

{"role": "user", "parts": [{"type": "text", "text": "I need waterproof hiking boots for day hikes, under $200"}]}

{"role": "user", "parts": [{"type": "image", "url": "https://…/photo.jpg"}]}

{
    "role": "user",
    "parts": [
        {"type": "text", "text": "find boots like these"},
        {"type": "image", "url": "data:image/jpeg;base64,..."},
    ],
}

{
  "role": "user",
  "parts": [
    { "type": "text", "text": "find boots like these" },
    { "type": "image", "url": "data:image/jpeg;base64,..." }
  ]
}

image.url accepts a data: URL or a public https:// URL. data: URIs are uploaded and rewritten server-side. If you send only an image, Channel3 finds the products in it (same as Find products in the image.).

What the agent sends

Assistant parts are text and tool. A tool part is one catalog call. Buy URLs already carry your affiliate tracking. The Product objects are the same type as the Search API. tool_name is search_products, show_products, compare_products, or image_search. The model may also run an internal lookup (lookup_products) that never appears in your UI. For search_products, show_products, and compare_products, render output.products as product cards.

{
  "type": "tool",
  "tool_call_id": "call_1",
  "tool_name": "search_products",
  "input": { "query": "waterproof hiking boots for day hikes under $200" },
  "output": { "products": [ /* Product[] */ ], "next_page_token": "…" }
}

image_search runs when the shopper sends a photo. Render output.things the same way as find-products-in-image: one heading per thing and a product rail from that group’s matches. There is no top-level products list on this tool.

{
  "type": "tool",
  "tool_call_id": "call_2",
  "tool_name": "image_search",
  "input": { "image_url": "https://…/photo.jpg" },
  "output": {
    "things": [
      { "thing": "lamp", "matches": [ /* Product[] */ ] },
      { "thing": "desk", "matches": [ /* Product[] */ ] }
    ]
  }
}

The assistant message may also include suggestions: tap-ready follow-ups for your UI, like “in brown instead”.

Getting Started

Make a Search

Get Product Data

Conversational Agent

Checkout

Pricing, Reporting, and Commissions

Build

Integrate

FAQ

Messages and Parts

What the shopper sends

What the agent sends

​What the shopper sends

​What the agent sends

What the shopper sends

What the agent sends