Retrieve user messages

The User Messages API fetches all active guest-facing messages sent to a registered user device. User devices can include mobile devices, wearable devices, responsive websites, and other user-facing touchpoints.

Once a user device is registered and has a valid appUserId, it can receive messages (refer to the Register user devices guide for additional information on this procedure). Messages are sent to registered user devices that meet all defined message rules. Defined rules can include scheduled times and dates as well as conditional triggers such as device location, geofence breaches, and user tags.

Retrieve active messages for a user

You can fetch all active (i.e., unexpired) messages for a single user across all venues using the GET verb:

1
2
3
4
curl -X GET \
  https://api.{region}.te2.io/v1/user-messages/me/messages \
    -H 'Authorization: Bearer {token}' \
    -H 'appUserId: {appUserId}'

Where:

• Authorization: JWT token returned during authentication.
• appUserId: The unique key that identifies the registered user device.

A 200 response returns an array listing of all active messages for the appUserId across all venues. The array includes detailed information about each message retrieved.

The payload can be lengthy depending on the number of messages and the number of venues.

Commonly used fields include:

• id: The unique identifier for the message.
• venueId: The unique identifier for the venue the message is associated with.
• subject: The message title.
• body: The message body.
• experienceId: The unique identifier for the experience that generated the message.
• experienceTitle: The title of the experience that generated the message.
• type: The message type. Possible message types include:
  • 1 - generic
  • 2 - alert
  • 3 - reward
  • 4 - offer
  • 5 - product
  • 6 - recommendation
  • 7 - reminder
  • 8 - smart recommendation
  • 9 - home
• publishTimestamp: The timestamp in ISO 8601 format when the message was sent.
• expireTimestamp: The expiration timestamp in ISO 8601 format for the message.

Links

For messages with an embedded link, the links array contains the following possible attributes:

• label: The display text for the link.
• type: The object type the link points to. Supported link types include:
  • coupon
  • event
  • poi
  • product
  • web
• target: The target of the linked object. This is dependent on the link type.

Images

For messages with an embedded image, the images array contains the size and source attributes for the associated image file.

Retrieve messages by venue

You can refine the payload by specifying a single venue using the venueId.

This is useful for filtering a user’s messages in a multi-venue app.

1
2
3
4
curl -X GET \
  https://api.{region}.te2.io/v1/user-messages/me/venues/{venueId}/messages \
  -H 'Authorization: Bearer {token}' \
  -H 'appUserId: {appUserId}'