RPI Queue Listener usage guide
Overview
This document provides some guidance on when Queue Listener (QL) functionality is appropriate to use and when it is not. There are various solutions that QLs support, and each comes with different behaviors that need to be considered to determine if a QL interaction is the correct one for your use case.
Details on Queue Listeners and configuring them can be found here.
About Queue Listener interactions
Queue Listener interactions are interactions that are primarily designed for messages that require rapid deployment and are triggered from data that is placed in a queue. The message can get into the queue in a few different ways, as listed below. The messages placed in the queue have a JSON payload that has all of the data components required to complete the interaction Queue Activity (fulfillment) and deliver the message via one or multiple channels.
Primary intention of Queue Listener functionality
Queue listeners were designed to allow external systems to trigger an outbound message from RPI with data based on the payload provided from the source system. This calling system will include the trigger key, the primary target address and all additional data required to drive personalization. The message will get processed in real time and delivered as fast as the outbound connector supports.
Content for QL messages using native connectors
Content for QL messages associated with native RPI channels is stored in RPI, like standard interactions. The difference is that the data that is used to personalize and support any of the dynamic content is expected to come from the data in the JSON payload that triggered the message.
Queue Listener limitations
There are some limitations on what you can do with Queue Listener interactions. For example, in order to process the records swiftly, the data in the primary data warehouse is not intended to be used, as it could significantly slow down the execution of the interaction.
Certain qualifications can be performed on the data in the payload and potentially the database, but there are restrictions to what can be performed and how long that additional processing adds to the length of time it takes to deliver the message from the time the system received it. Additional details on qualification rules can be found on this page.
Queue listeners can also use data that is in the Realtime visitor profiles to supplement or add data to the QL payload. Given that data retrieval from the visitor cache is very fast, it is acceptable to be used as a data source for QLs.
Features applicable to Queue Listener
Some features of standard interactions are available in Queue Listeners, where others are not. For instance, you can create a Smart Asset using the values contained in one of the payload attributes. However, you cannot customize payload attributes or manipulate the underlying data using a function, like you can with custom attributes and functions on database fields. Below is a list of a few key features you can and can’t use in QLs, but it is not comprehensive list.
✅ Features you can use with QLs
Personalized content
Dynamic content (Smart Assets)
Based on payload data
Attribute Smart Asset
Rule Smart Asset
Table Smart Asset
Capture metadata
❌ Features you can NOT use with QLs
Custom attributes (except parameters)
The only custom attribute that you can use with QL data that comes in the JSON payload is a parameter attribute.
Enrich data with database attributes
Personalize data with database attributes
Key parts of Queue Listener payloads
This table lists the key components that make up the JSON payload for Queue Listener messages.
Attribute | Description |
|---|---|
| This is the GUID that identifies a specific QL interaction. |
| This is the primary target address of the recipient (email, SMS, other). |
(Customer-defined) | This is the set of data that has a single value per attribute, e.g., first name or order number for an order confirmation email. |
| This is the set of data that has multiple rows of values associated with the asset, e.g., order item details like item name, description, and cost. If multiple items were bought, there would be multiple rows provided. |
Ways a Queue Listener can be triggered
There are a few ways that you can get messages into the queue that Queue Listeners are configured to use.
Call to Interaction API
Call to Realtime API
Message placed directly in the queue
Message triggered by a web event
How Queue Listeners work
Generally speaking, these are the high-level execution steps when a queue listener is executed:
Message placed in the queue
Queue Listener triggered
Queue Activity executed (offer/extract)
Payload data written to QL database table
Offer History data written
Data that is written to the Queue Listener table is configurable and allows you to capture all or some of the data elements provided in the payload. In addition to the QL table, you can configure what gets written to the Offer History table when any outbound communication is made.
When to use Queue Listener interactions
Now that you know what Queue Listeners are, how to trigger them, and how they work, you need to consider if they are viable for your use case. Not all use cases require or are suitable for queue listener interactions. In this section, we identify some ways to determine if a QL is suitable for your use case or not, and some potential use cases that queue listeners could be used for.
Queue Listener interaction candidates
The primary goal of Queue Listeners is to receive a call in real time and execute an outbound action “immediately” upon receiving that message. (“Immediately” is in quotes, as it still allows for some variability in the timing of the message sends.) This is where we start to consider the intent of the message going out, the timeliness requirements of receiving the message, and if a QL is a viable option for your use case.
A QL message is typically triggered on an event or action such as a form being filled out, an order being placed, or a web session ending. Some of these may trigger operational type messages like a password reset request or marketing type messages where someone signs up for the loyalty program.
Campaign requirements and Queue Listeners
Below is a simple decision tree to help determine if a QL is the right fit for your use case along with a brief matrix of some requirements and if those requirements align with using a Queue Listener interaction.
Table of requirements and associated notes
Requirement | Suitable for QL | Notes |
|---|---|---|
The communication needs to be sent ASAP | Yes | Messages that need to be delivered within 10 minutes or faster of an action or event is a good benchmark when considering if QL messages are the right solution for your use case. |
The calling system provides all data required for fulfillment | Yes | |
There are sophisticated segmentation requirements | No | |
There is data in the primary data warehouse or auxiliary database that is required | Maybe | The data may be accessible under certain conditions, but may slow down processing time. |
The campaign requires features not supported by QL | Maybe | Things may be able to be addressed upstream and bypass the limitation. An example may be formatting data upstream before sending to QL. |
Use cases
Now that we have reviewed some qualifications that make a campaign eligible for a QL interaction, we can look at some campaign types and if they are suitable for a QL interaction or not.
As mentioned above, if the source system has all of the data to support the requirements of the campaign and the message needs to be sent out rapidly, then a QL interaction may be the correct choice.
Given this, QLs are well-suited to operational types of emails. Operational emails do not require validation that a recipient is opted in to receive emails, so the database would not be required to check that preference.
Here are some examples of campaigns and use cases that are suitable and those that are not. Keep in mind that it is expected that QLs are triggered and executed immediately with no significant decisioning, so although order confirmation is on the list, it is expected as a pass-through with personalization, smart assets, and other supported features of QLs.
✅ Good use cases for QLs
Password reset emails
Order confirmations
Abandonment of cart/browse reminders (if triggered by external systems)
❌ Avoid QLs when
You need to segment or filter audiences
You rely on other data joins or enrichment
The message doesn’t need to go out ASAP
Potential queue listener communications
Here are a few different communications and associated communication type and delivery timing targets.
Communication | Communication type | Delivery timing target |
|---|---|---|
Welcome email | Operational | Real time |
Password reset | Operational | Real time |
Order confirmation | Operational | Near real time - up to 10 minutes |
Order shipment | Operational | Within hours of shipment |
Abandon cart | Marketing | Immediately after session expires - within a day of session expiration |
Abandon browse | Marketing | Immediately after session expires - within a day of session expiration |
Additional information on Queue Listeners
Above we listed the primary details on what a QL is, how it works, and when to use them. This section provides some additional notes on various aspects of QLs and their features.
Journey campaigns with QL as initial message
It is not uncommon that a QL message is the first message sent to you in a series of messages for a campaign journey, for example a welcome series. You sign up based on a form online, and the initial message is triggered through a QL, and the follow up messages are just standard interactions based on the data that was captured from the payload in the QL table. These interactions are like standard interactions, except the resolution and audience definition are linked back to the QL table. That table is unique on RPIResolutionKey, and every record inserted to the table gets its own ID. This allows for you to perform subsequent touch points after the initial communication.
Data intake
Queue Listener interactions offer a programmatic way for RPI to ingest data into the environment. You can use a QL interaction and have the Queue Activity use a control fulfillment activity, which will effectively load the data to the database and do nothing additional. This approach can be used on its own or in support of the Near-real time with segmentation or filter logic section.
Near-real time with segmentation or filter logic
There are times when a QL message makes sense from a source system and timing perspective, but the limitation of applying additional segmentation or filter logic make the campaign a bad candidate for QL interactions. There is an option that may still make a QL interaction the right one for your use case. You can use a QL to stage the data in the QL table, as noted by data intake above. Then you can use a standard interaction on the QL data as the initial touchpoint of the communications, but with additional logic (segmentation).
Like journey-based campaigns where the initial QL message was a communication, instead it will just be captured as a control so that a standard campaign can use the data and apply the additional segmentation and logic. Because we need to capture the data and then run a standard interaction on the data, that requires a delay due to the multiple steps. This could increase the delivery time from seconds to multiple minutes or longer. This is why we are referring to this as “near-real time,” as there will be a delay of some sort do to the additional steps.
Message reconciliation and unique message IDs
When using QLs or any API-based messaging system, it is reasonable to expect that you need to validate that the message that was sent from the source system was received and acted on by the target system. By providing a unique message ID as a part of the message sent to the queue, you will be able to create a process to perform this confirmation. It is always recommended to include a unique message ID in case you ever need to perform any validation.