Message Service

The message service provides endpoints which allows a user to retrieve messages and notifications for their account.

Endpoints

Get Notifications for Guest

GET message/myMessages.json

Obtains a list of messages for the user which have not been deleted.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • username (String) – (required) The username (login) of the user.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • messages (List[Object]) – (required) See Message for format of the objects.
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Delete Notification

DELETE message/deleteMessage.json

Delete a single message associated to a user.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • username (String) – (required) The username (login) of the user.
  • messageCode (Long) – (required) The unique code for this message.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • code (Long) – (required) The code of the message that was deleted.
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The (human readable) error message of the failure.

Constant Values

messageContextType Values

INVITATION_CODE
A Social Group Invitation code
WALLET_CODE
A Wallet code
GIFT_CODE
A Gift code (also called a Transfer)
CHALLENGE_CODE
A Challenge code
USER_CODE
A User code
ACCOUNT_CODE
An Account code (for a particular user)
CARD_NUMBER
The user/account’s card number
MEMBER_CODE
A Social Group Member code
STORE_CODE
A Store code
CARD_TEMPLATE_CODE
A Card Template code
TIER_CODE
A Tier code
PERK_CODE
A Perk code
SOCIAL_GROUP_CODE
A Social Group code
SAL_ORDER_CODE
A Sale Order code
CHALLENGE_OCCURRENCE_CODE
A particular instance of a Challenge (if a user took a challenge multiple times)

messageType Values

USER_REQUESTS_JOIN
User requests to join group
GROUP_INVITES_USER
Group invites a user to join
USER_ACCEPTS_INVITATION
User accepts invitation to join group
USER_REJECTS_INVITATION
User rejects invitation to join group
REQUEST_CANCELLED
Request to join a group was cancelled
INVITATION_CANCELLED
Invitation to join group was cancelled
GROUP_ACCEPTS_REQUEST
Group accepts request to join
GROUP_REJECTS_REQUEST
Group rejects request to join
MEMBER_LEAVES
Member leaves group
MEMBER_REMOVED
Member removed from group
CHALLENGE_COMPLETED
The challenge being taken by the user/group was successfully completed
CHALLENGE_EXPIRED
The challenge being taken by the user/group expired
CHALLENGE_ENTERED
The user/group entered into a challenge
CHALLENGE_ELIGIBLE
The user/group is eligible to take a challenge
CHALLENGE_EXPIRING
The challenge being taken by the user/group will expire soon
REWARD_EXPIRING
A reward/points/dollars will expire soon
GIFT_RECEIVED
The user received a gift
GIFT_RETURNED
A gift a user sent was returned
GIFT_REJECTED
A gift a user sent was rejected by the recipient
GIFT_ACCEPTED
A gift a user sent was accepted by the recipient
GROUP_EARNED_POINTS
A user’s social group earned them points/rewards

sourceType Values

SYSTEM
System
MERCHANT
Merchant
USER
User
CAMPAIGN
Campaign
SOCIAL_GROUP
Group

Reply Objects

Message
JSON Parameters:
 
  • code (Long) – (required) The unique code of this message.
  • message (String) – (required) The text of the message.
  • messageType (String) – (required) The type of the message. Indicates the action or event which generated the message. See messageType Values.
  • sourceType (String) – (required) The source of the message. Indicates the application or user which generated the message. See sourceType Values.
  • senderName (String) – (required) If available, this is the name of the user who was the source of the message.
  • senderAvatarCode (String) – (required) If available, this is the avatar code of the user who was the source of the message.
  • contextType (String) – (required) The type of the context code. The “context” of the message provides the caller with information that can be used to obtain further information to be displayed in association with the message. For example, if the message says “You completed the challenge Eat Everything On The menu”, contextType might be CHALLENGE_CODE and the contextCode would be the unique code for the particular challenge. The caller could then make another REST call (e.g., to the Challenge Service) to get the details of the challenge to display along with the message (like, long description, challenge image, etc.). See messageContextType Values.
  • contextCode (String) – (required) If available, this is a code value specified by the contextType.
  • contextLabel (String) – (required) If available, this is a short label describing the item specified by the code.
  • contextDescription (String) – (required) If available, this is a long description describing the item specified by the code.
  • contextImageCode (String) – (required) If available, this is a code or partial URL or absolute URL used to specify an image for the item specified by the code.
  • contextLink (String) – (required) If available, this is a URL for a page describing the item specified by the code.
  • contextLinkLabel (String) – (required) If available, this is the label for the contextLink.
  • date (Date) – (required) The date that this message was created.

Error Codes

The following are the possible codes and messages that can be returned by the Message Service.

There are other system-level errors which may be returned which are not documented here.

The caller of the endpoint can use the returned message to display to the end user or, if different wording is desired, can provide their own mapping of code to message.

Code Message
message.not_implemented Not yet implemented
message.user_not_found User not found
message.messages_lookup_error Unable to get messages
message.insert_message Unable to add message
message.message_not_found Message not found
message.delete_message Unable to delete message
message.invalid_argument Invalid argument
message.system_error System error