Skip to main content

Message service

Overview​

The Message service works like an asynchronous event bus. It allows components to send out notifications about platform actions and lets other services listen for these messages.
Messages may be filtered before they are sent, as well as before they are received. Message senders typically filter messages based on whether or not a listener is authorized to receive the messages they send. Message receivers can filter messages to receive only those messages they are interested in.
Messages can be delivered over REST/HTTP, or they can be delivered via Google Cloud PubSub. Only the delivery via Google Cloud PubSub honors the ordering constraints that can be added to messages when they are sent.

Communication between systems

Listening to messages enables your software to respond to changes that happen on the Banqup platform. Sending messages allows your software to communicate with interested parties on the Banqup platform in a decoupled scalable way.

Two of your own software systems can even respond to each other's events through Banqup.
For example, consider a setup that features two software systems: one movie ticket reservation application, and one loyalty and rewards application. After a customer makes a reservation and pays for that reservation, the ticket reservation application receives a message from Banqup which informs it that the user's payment was successful. The ticket reservation system then correlates the payment with a reservation, and subsequently sends a message that indicates the customer has successfully completed a reservation. If the loyalty and rewards program application is a message listener, it will then receive that message, and can assign reward points to the customer. That in turn can trigger a push notification on the customer's phone.

Available plugin interfaces​

Listening to/receiving messages is possible by implementing a plugin interface. Sending messages on the other hand requires calling the Send Message endpoint on the message service. Note that senders must be granted permission to send messages of a specific category.

The following plugin interfaces may be implemented in order to integrate with Banqup by using the Message service:

  • Message Listeners: Implement this plugin interface to start receiving messages from Banqup.
    Check out the recipe Set Up A Message Listener to learn how to register a message listener.
  • Message Authorizers: Implement this plugin interface to define message filters that must be applied before a message is sent to a message listener.

In summary, message senders are in control of:

  • what is sent
  • who may listen to messages
  • what the order of messages is (if any) between broadcast messages, see Message API introduction for more.

Delivery​

Messages can be delivered in one of three ways:

  • If the receiving application implements the messageListener plugin interface, i.e. message listeners, messages can be delivered to a REST endpoint.
  • Alternatively, those message listeners may request delivery to a Google Cloud PubSub topic.
  • Applications can opt for delivery via message channels, which is based upon Service Side Events (SSE). The usage of message channels does not require implementing the messageListener plugin interface.

Receiving via REST endpoint vs. Google Cloud PubSub​

First, messages sent to REST endpoints may arrive in any order. In contrast, messages delivered to PubSub will maintain the same sequence in which their send-message-requests were originally received by the Message Service.

Second, there are differences in what happens if the delivery of a message fails.

If a REST endpoint delivery fails (e.g. when a message listener returns an HTTP 500 status code), the system will automatically retry the delivery multiple times. These retries follow an exponential backoff pattern and may continue for up to two days.

On the other hand, once a message is delivered to a PubSub topic, receivers control the retry policy through PubSub's subscription settings. It is important to note that if a message cannot be delivered to a PubSub topic, the message listener will be deregistered automatically. Such failures only happen when there is a configuration/permission problem. If you wish to receive a notification email when deregistration happens, ensure that the owner's email address is registered when plugging in a Message Listener. For more information, see Ordered delivery/PubSub in the Message API introduction.

The diagram below shows the typical flow that registers a message listener and how messages are delivered and filtered when they are sent. Once your application completes the registration process (steps 1a-1f), the Message Service will deliver any messages sent by Banqup applications or extensions (steps 2a-2b) directly to your software application.

Registering a message listener and receiving messages

For a successful implementation, choose the appropriate delivery mechanism for your application.

Message channels​

Some applications are not able to either host a REST endpoint or read from a PubSub subscription, therefore they cannot implement the plugin interface messageListener. Typically this category of application is user facing, i.e. web UI, mobile applications. Instead, these applications may use a delivery mechanism called message channels. Message channels deliver messages in order via Server-Sent Events (SSE).
To prevent these applications from being overwhelmed with information, message channels provide a more dynamic approach to filtering messages. This means that an application can keep a single connection open to the Message service and will only deliver events to the application for spaces/documents that it is interested in.

The diagram below illustrates the chain of events for an application that receives messages via message channels.

In step 1a, a user facing application, e.g. a web UI, creates an event source with subscriptions on events that it is interested in. The Message service verifies with all required message authorizers that the web UI may indeed become a subscriber (step 1b). The message authorizers have no objections (step 1c) and the event source is created (step 1d). The web UI and Message service then retrieve all events from the event source it just created (steps 2a and 2b). Later, when another Banqup application or extension sends a message that the web UI is subscribed to (steps 4a and 4b), the Message service will use the same connection to emit a Server-Sent Event to the web UI that contains the message (step 2c).

Typical message channel use case

Message channels come with a tradeoff. Messages that cannot be delivered (e.g. because the receiver is unreachable), will not be retried. To somewhat reduce the impact of this, a message channel can redeliver some events if request 2a in the above diagram includes a Last-Event-ID HTTP header.
When configured with the message ID of the last received message, the Message service will attempt to replay all events from that point onward. However, there is no guarantee that this will happen, so be prepared to restart the connection and handle the uncertainty that some messages might have been missed. Typically this means invalidating a cache or model and reinitializing it.

More resources​

For more information on the API of the Message service, refer to the Message API introduction and documentation. It describes what API calls and REST resources are available on the Message API.