Skip to content

Offer Manager

A quick guide to items created and managed in Advertising.chat

This reference lets you know about the key elements that make up an Advertising.chat deployment. To learn more about each of these elements, follow the links or browse or search the help center.

Moments

A moment is a logical point in a conversation at which you may want to insert dynamic messaging. Any advertising or other content delivered by Advertising.chat happens at a particular moment.

Each moment has a unique code, used for the one-time configuration of your chatbot, that allows Advertising.chat to identify a logical point in a conversation.

Moments are similar to ad units in web advertising.

Offers

An offer is a specific advertisement that gets delivered to users. Offers in Advertising.chat are flexible and powerful, and may be anything from a simple text message to an RCS carousel with images, videos, application links, and other complex interactions.

Offers are similar to creatives in web advertising.

Rules

A rule holds information about the specific run dates, targeting criteria, and other delivery rules of one or a set of components that will be delivered. Rules are associated with a specific moment, and all the rules for a particular moment together control which components show up at that moment.

Rules are similar to line items in web advertising.

Other Elements

API Keys

An API Key is used to programmatically identify a software component when using Advertising.chat application programming interfaces (APIs). API Keys serve to associate API requests, such as fetch requests and conversion tracking, with a specific Advertising.chat network (account).

Actions

An Action may be associated with a messaging component in order to facilitate specific subscriber interaction, such as navigation to a web link, or invoking a phone call. Actions are created as part of the offer with which they are associated.

When a user interacts with an Action, information about the interaction is collected by Advertising.chat and made available as part of the analytics and reporting. Tracking these interactions allows Advertising.chat to calculate performance metrics such as clickthrough and conversion rates for offers.

Offers

Working with offers.

An offer is a specific advertisement that gets delivered to users. Offers in Advertising.chat are flexible and powerful, and may be anything from a simple text message to an RCS carousel with images, videos, application links, and other complex interactions.

Supported Offer Types

SMS Text Offer

The SMS Text Offer is used to define the body of an SMS text message. Advertising.chat allows SMS Text Offers to utilize keyword substitution to customize or personalize the payload of the message according to each request, and allows for a single action (link) to be included in the message.

If the length of an SMS Text Offer exceeds 160 characters after applying keyword substitution and link shortening, the message text that appears immediately before the action link will be truncated to reduce the size to 160.

Danger

SMS text offers are deprecated. Use Universal offers instead.

Universal

The Universal offer format allows for the delivery of a Rich Card to the subscriber, which includes thumbnails, title, description, and other elements. Universal offers degrade gracefully for delivery via SMS.

Universal offers may have associated suggested actions and/or replies.

Associating Actions with Offers

Universal offers may contain an optional set of associated suggested replies and/or actions that are presented to the user as a tapable "chip list" displayed just after the component in the subscriber's messaging application.

Supported actions may include web hyperlinks, dialer (phone call) actions.

To associate an action with an Offer, tap the "ADD ACTION" button that appears below the component definition.

Associating Custom Properties with Offers

Offers may have optionally have any number of custom properties associated with them. These custom properties are simple name/value pairs that may be used for application-specific purposes.

Custom properties do not affect the appearance or behavior of offers, but are available to applications as part of any fetch response referencing the offer. Custom properties can also be included in journal reports.

An application might use custom properties to associate a house or direct-sold offer with an application-specific campaign id, or it could record meta information about a particular offer.

Using keyword substitution in text offers.

When a text creative has an associated action (weblink), you can control the position of the link in the message using the string ${@actionUrl}. For example, to have a link in the middle of a message, you might enter:

"More information can be found at ${@actionUrl}, or just reply MORE."

Any targeting parameter that was supplied in the fetch request may be used as a substitution variable in an offer message. Simply use the syntax ${KEY} to insert the value of a targeting parameter named "KEY" in a message. For example, if you are sending a targeting parameter named "FirstName" in a fetch request, you might use:

"Thanks for your message, ${FirstName}."

At runtime, if a request was received with targeting parameter of FirstName=Omar, it would resolve to:

"Thanks for your message, Omar."

Default values

We do not currently support default values for targeting parameters. If a substitution value is provided with no matching targeting value, no text will be substituted.

Rules

Working with rules.

A rule holds information about the specific run dates, targeting criteria, and other delivery rules of one or a set of components that will be delivered. Rules are associated with a specific moment, and all the rules for a particular moment together control which components show up at that moment.

Rules are similar to line items in web advertising.

To create a new rule, navigate to https://console.advertising.chat/rules and select the "Create Rule" button in the upper-right. Select the moment with which the rule should be associated, and then select one or more offers to serve when the rule matches.

A rule will match a fetch request if (and only if):

  1. The rule is associated with the same moment as specified in the request,
  2. All of the targeting criteria specified by the rule match the targeting information associated with the request,
  3. The rule is enabled.

Using Dates in Targeting Criteria

You configure each rule with targeting criteria that specifies the conditions that must match for the rule to be applied to an incoming fetch request. These criteria take the form of "<Key> <Condition> <Value>", where <Key> is the name of an attribute passed in with the fetch request, <Condition> is an expression like "is" or "is greater than", and <Value> is a literal value you supply that will be compared with the value of <Key> provided in the fetch request.

Although all attributes passed to the fetch APIs come in as strings, the logical type of a value can be one of: text, number, or date. The Advertising.chat Console indicates the implied type of each value under the "condition" field of each targeting criterion. You can specify the type that should be used for interpreting an attribute value in the Console by clicking the desired value.

As noted above, targeting criteria may be written for attributes that represent calendar dates. This allows rules to be written for situations like "expirationDate > 2020-03-15". When the date type is specified for a rule, the attribute value provided in the fetch request is parsed as a date (rather than as a simple string or number), and comparisons are performed on the represented calendar dates as you would expect. In order to unambiguously specify that an attribute / rule is to be treated as a date (and not as a number or text), be sure that you have selected date under the "Condition" field in the Advertising.chat console.

When a date is specified as a condition Value in the console, the date value will be taken to represent a specific calendar day in the local timezone (that is, in the timezone associated with the Advertising.chat account). Thus, a rule written for an account configured in the "Americas/New_York" timezone, and requiring that a "startDate" attribute must equal "2020-01-02", will evaluate to true whenever the value given for startDate falls on January 2, 2020 after having been converted to the New York timezone. So for example a startDate value provided in a fetch request of "2020-01-01T23:30:00-07:00", which represents 11:30 PM on January 1st, 2020 on the west coast will match the configured date of "2020-01-02" because that timestamp falls on January 2nd when converted to the New York timezone.

Date comparisons consider only the timezone-adjusted calendar day, and ignore any time-of-day offsets. So for example the two values of "2020-01-02" and "2020-01-02T21:30:00" will (assuming timezones are the same) be treated as equal for the purpose of comparisons.

Keep these things in mind when using date-valued attributes:

  1. The attribute's value (passed in the fetch request) should be given in ISO 8601 format (e.g., '2015-02-03' or '2019-03-06T13:45:00-04:00'). RFC 2822 Date time format may also be used.
  2. The Value date specified in the console for matching is taken to be a calendar day in the local timezone. Attribute values will be converted to this timezone before comparison.
  3. Once converted to the same timezone, any time-of-day information in a value will be ignored for the purpose of date comparison.
  4. If dates are specified without a timezone specified, the default timezone for the account will be used. This applies both the date values provided in attributes as well as the date value provided in the user interface.

Fallback Rules

It is sometimes desirable to have a fallback rule to act as a "catch all" for a particular Moment. For example, you may have specified individual offers to present to users in specific circumstances, but you have a default response that you want to present in the event none of the special cases is matched.

You can create a fallback rule for this purpose in the Advertising.chat Console. Fallback rules are eligible only in the case that no other rule matched a given request, giving you an opportunity to provide a "default" or "catch-all" rule that will specify what to do when no specific rule has matched. Fallback rules are only eligible to fulfill a fetch request in cases where the request would otherwise not return an offer to the user.

To create a fallback rule:

  • Navigate to https://console.advertising.chat/rules
  • Create a new rule, or edit an existing rule
  • On the New Rule (or Edit Rule) page, near the bottom, enable the "Use as Fallback" slider.

Note

Because a normal (non-fallback) rule might match a request but fail to fulfill it (e.g., when all of its associated offers have reached their frequency caps), it is possible that a fallback rule will be invoked even in situations for which a normal rule is configured. This is normally what is expected, but might not be immediately obvious.

Multiple Fallback Rules and Targeting

You will normally not specify any targeting criteria for fallback rules, choosing instead to use a single fallback rule as a true "catch-all" for a given Moment. But there are some situations where it is desirable to have more than one fallback rule, and you may wish to use targeting criteria to select between them. For example, you may have two fallback rules for the same Moment, one for existing customers and another for new customers. To configure the rules appropriately, you would specify targeting criteria as normal for each rule, enabling the "Use as Fallback" option for each.

Targeting criteria are enforced for fallback rules just as they are for normal rules.

Keep in mind, however, that fallback rules are only considered after all other (non-fallback) rules have been given the opportunity to respond to a fetch request.