Moments, offers, and rules¶

Offer Manager decides which offer, if any, appears at a given point in a conversation. You describe that decision with three objects: moments, offers, and rules. This page defines each one and explains how they combine when your agent asks for an offer. For the product overview, see Offer Manager.

The examples in the Offer Manager pages use a resort's concierge agent, which talks with guests over RCS and offers them a spa booking after they check in.

Agents¶

An agent is one of your org's conversational programs, such as a sales agent or a customer-care agent; in the API it is an application. Moments and rules belong to exactly one agent, chosen when you create them, and offers belong to the org, so any agent's rules can show the same offer. See Agents.

Moments¶

A moment is a named point in a conversation where an offer could fit, such as after a guest checks in, after a question is resolved, or before the conversation ends. Your agent decides when a moment has arrived. At that point it asks Advertising.chat for an offer and names the moment by its Code. Each moment belongs to one agent.

Each moment has the following properties:

Property	Description
Moment Name	A display name for the console.
Agent	The agent the moment belongs to. Set when you create the moment.
Code	The identifier your agent sends with each request. Codes are unique within an agent, so two agents can use the same code.
Description	Optional notes for your team.
Enabled	Whether the moment serves offers.
Frequency Cap	The most offers one customer sees at this moment, from None to 1 / three months.

Offers¶

An offer is the content a customer sees: a product, an upgrade, a booking, or a partner's service. Offer Manager renders each offer natively for the channel the request names. On RCS it is a rich card, on SMS it is text followed by a link, and on webchat it is a card.

An offer has the following parts:

Title, Subtitle, and an image, which make up the card.
Alt Text, the text used where a card can't be shown. On SMS, the message is the alt text followed by the offer's link.
Actions, the buttons or suggested replies shown with the card. Each action has an Action Type of Text (a suggested reply), Navigate (open a link), or Call (dial a phone number), plus Display Text and the Action value itself.
Custom properties, name and value pairs returned with the offer for your agent's own use. They don't change how the offer looks.
Frequency Cap, the most times one customer sees this offer.

Links in Navigate actions are returned as click-tracking URLs, so a tap is recorded before the customer reaches the destination.

Rules¶

A rule decides when offers are eligible at a moment and how they compete with the offers of other rules. A rule belongs to one agent, and connects one or more of that agent's moments to one or more offers. It has the following properties:

Property	Description
Agent	The agent the rule belongs to. Set when you create the rule.
Offer	The offers the rule can show, and how it chooses among several: the one that earns the most engagement per request, while still showing every offer some of the time, or each in turn in the order listed.
Who sees it	The rule's audience: the customers it is for, from the attributes your agent sends and each customer's past responses. See Rule conditions.
When	The agent's moments where the rule applies.
Where	The channels the rule serves on, or every channel.
Not shown to	The rule's exclusions: the customers removed from the audience.
How often	The most times one customer sees the rule's offers in a period.
Schedule	The dates, days, and hours the rule serves, in your org's time zone.
Priority	High, Normal, or Low. Among the rules that qualify for a request, a rule in the highest priority present wins.
Status	Active or Paused.
Delivery limit	An optional cap on the rule, by total serves or by share of matching requests.
Fallback	Makes the rule a fallback rule, described in the next section.
Test mode	Marks the rule's responses as tests (`isTest: true`), so that your integration can avoid sending them to customers.

The console shows the first nine as sentences on the rule's offer card, the status beside the rule's name, and the rest on its Advanced tab.

Every field of a rule as the API stores it, including audience, exclusions, channels, schedule, and frequency, is in the Rule reference.

Fallback rules¶

A fallback rule is considered only when no other rule for the moment qualifies. Use one to set a default offer for a moment that applies when none of your specific cases match. Fallback rules still have to pass their own limits and conditions, so you can have more than one fallback rule for a moment and separate them by audience, such as one for new customers and one for returning customers.

A normal rule can qualify for a request and still return nothing, for example when the customer has reached the frequency cap of every offer it holds. In that case a fallback rule can serve even though a normal rule applied to the request.

How a request is decided¶

When your agent asks for an offer at a moment, Offer Manager evaluates the moment's enabled rules in this order:

It checks the moment's Frequency Cap. If the customer has reached it, the response is empty.
It sets aside fallback rules, and removes rules that have reached their Limit.
It removes rules whose channels, schedule, audience, or exclusions don't match the request. A rule whose exclusions remove only some of its offers continues with the rest.
It removes rules with no offer that can render in the requested channel format.
If no rules remain, it applies steps 2 through 4 to the fallback rules.
It removes rules whose frequency cap the customer has reached.
Among the remaining rules, the highest Priority wins. Within a priority, the conversation's context and each rule's recent engagement weigh the choice.
The winning rule picks one of its offers that the customer has not yet seen as often as its Frequency Cap allows. The offer is rendered for the channel and returned.

If nothing remains after these steps, the response is empty, and your agent continues the conversation without an offer. An empty response is the common case, and a well-behaved agent expects it.

When the request includes conversation context, an appropriateness check can also return an empty response in a sensitive moment, such as a complaint or a health concern. See The context parameter.

Names in the console and the API¶

The console and these docs use the Offer Manager names. The Offer Manager API and the Fetch API use the names on the right.

Console	API
Agent	Application (`application`)
Moment	Ad unit (`adUnit`)
Offer	Creative
Rule	Line item