.. _message_service: Message Service =============== The message service provides endpoints which allows a user to retrieve messages and notifications for their account. .. contents:: Topics Endpoints --------- Get Notifications for Guest ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`b2b_auth` * :ref:`guest_user_auth` * :ref:`oauth_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :query String username: *(required)* The username (login) of the user. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam List[Object] messages: *(required)* See :http:jsonentity:`Message` for format of the objects. .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. Get Notifications for Guest by Printed Card Number ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:get:: message/myMessagesByPrintedCardNumber.json Obtains a list of messages for the user which have not been deleted. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` * :ref:`oauth_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :query String printedCardNumber: *(required)* The user's printed card number. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam List[Object] messages: *(required)* See :http:jsonentity:`Message` for format of the objects. .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. Delete Notification ~~~~~~~~~~~~~~~~~~~ .. http:delete:: message/deleteMessage.json Delete a single message associated to a user. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` * :ref:`guest_user_auth` * :ref:`oauth_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :query String username: *(required)* The username (login) of the user. :query Long messageCode: *(required)* The unique code for this message. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam Long code: *(required)* The code of the message that was deleted. :jsonparam String message: *(required)* The content of the message that was deleted. .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. Delete Notification by Printed Card Number ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:delete:: message/deleteMessageByPrintedCardNumber.json Delete a single message associated to a user. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` * :ref:`oauth_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :query String printedCardNumber: *(required)* The user's printed card number. :query Long messageCode: *(required)* The unique code for this message. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam Long code: *(required)* The code of the message that was deleted. :jsonparam String message: *(required)* The content of the message that was deleted. .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. Format Message ~~~~~~~~~~~~~~ .. http:get:: message/formatMessage.json Format a message. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :query String sourceType: *(required)* The source of the message. Indicates the application or user which generated the message. See :ref:`source_type`. :query String eventType: *(required)* The event type for this message. See :ref:`event_type`. :query String targetType: *(required)* The target of this message. See :ref:`target_type`. :query Map[String->String] params: *(required)* Parameters to be substituted. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam String value: *(required)* The formatted message. .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. Constant Values --------------- .. _message_context_type: ``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 ``SALE_ORDER_CODE`` A Sale Order code ``CHALLENGE_OCCURRENCE_CODE`` A particular instance of a Challenge (if a user took a challenge multiple times) ``BADGE_CODE`` A Badge Code ``SURVEY_CODE`` A Survey Code .. _source_type: ``sourceType`` Values ~~~~~~~~~~~~~~~~~~~~~ ``SYSTEM`` System ``MERCHANT`` Merchant ``USER`` User ``CAMPAIGN`` Campaign ``SOCIAL_GROUP`` Group ``CHALLENGE`` Challenge .. _event_type: ``eventType`` Values ~~~~~~~~~~~~~~~~~~~~~ ``CHECKIN`` Checkin ``NEW_PENDING_TRANSFER`` New Pending Transfer ``TRANSFER_ACCEPTED`` Transfer Accepted ``TRANSFER_REJECTED`` Transfer Rejected ``TRANSFER_RETURNED`` Transfer Returned ``CAMPAIGN`` Campaign ``REFERRAL_COMPLETED`` Referral Completed ``REGISTER`` Register ``ATTACH`` Attach ``GUEST_MESSAGING_RULE`` Guest Messaging Rule ``ADMIN_MESSAGING_RULE`` Admin Messaging Rule ``REVERSE_ENROLL`` Reverse Enroll ``SOCIAL_GROUP_USER_REQUESTS_JOIN`` Social Group User Requests Join ``SOCIAL_GROUP_GROUP_INVITES_USER`` Social Group Group Invites User ``SOCIAL_GROUP_USER_ACCEPTS_INVITATION`` Social Group User Accepts Invitation ``SOCIAL_GROUP_USER_REJECTS_INVITATION`` Social Group User Rejects Invitation ``SOCIAL_GROUP_REQUEST_CANCELLED`` Social Group Request Cancelled ``SOCIAL_GROUP_INVITATION_CANCELLED`` Social Group Invitation Cancelled ``SOCIAL_GROUP_GROUP_ACCEPTS_REQUEST`` Social Group Group Accepts Request ``SOCIAL_GROUP_GROUP_REJECTS_REQUEST`` Social Group Group Rejects Request ``SOCIAL_GROUP_MEMBER_LEAVES`` Social Group Member Leaves ``SOCIAL_GROUP_MEMBER_REMOVED`` Social Group Member Removed ``SOCIAL_GROUP_CHALLENGE_COMPLETED`` Social Group Challenge Completed ``SOCIAL_GROUP_CHALLENGE_EXPIRED`` Social Group Challenge Expired ``SOCIAL_GROUP_CHALLENGE_ENTERED`` Social Group Challenge Entered ``SOCIAL_GROUP_CHALLENGE_ELIGIBLE`` Social Group Challenge Eligible ``SOCIAL_GROUP_CHALLENGE_EXPIRING`` Social Group Challenge Expiring ``SOCIAL_GROUP_REWARD_EXPIRING`` Social Group Reward Expiring ``SOCIAL_GROUP_GROUP_EARNED_POINTS`` Social Group Earned Points ``HELP`` Help ``OPT_OUT`` Opt Out ``OPT_IN_VERIFICATION`` Opt In Verification ``ENROLLMENT`` Enrollment ``UNKNOWN_REQUEST`` Unknown Request ``ENTER_REGION`` Enter Region ``ECLUB_REGISTER`` Eclub Register ``RESET_PASSWORD`` Reset Password ``REGISTRATION_EMAIL_VERIFICATION_REQUIRED`` Registration Email Verification Required ``SURVEY_PARTICIPANT_ENTERED`` Survey Participant Entered ``SURVEY_PARTICIPANT_COMPLETED`` Survey Participant Completed ``EXTERNAL_NOTIFICATION_RULE`` External Notification Rule ``MOBILE_PAYMENT_RECEIPT`` Mobile Payment Receipt ``REFERRAL_INVITATION`` Referral Invitation ``WEB_EGIFT_ORDER_CONFIRMATION`` Web Egift Order Confirmation ``WEB_EGIFT_ORDER_SUSPENDED`` Web Egift Order Suspended ``WEB_EGIFT_ORDER_ITEM_FULFILLMENT`` Web Egift Order Item Fulfillment ``WEB_EGIFT_FREE_ITEM_FULFILLMENT`` Web Egift Free Item Fulfillment ``ONE_TIME_RECHARGE`` One Time Recharge ``AUTO_RECHARGE_ENABLE`` Auto Recharge Enable ``AUTO_RECHARGE_SUCCESS`` Auto Recharge Success ``MOBILE_WALLET_DELIVERY`` Mobile Wallet Delivery ``REST_MESSAGING_TRANSACTIONAL`` REST Messaging Transactional ``WALLET_EXPIRATION`` Wallet Expiration ``POINTS_CHALLENGE_PROGRESS`` Points Challenge Progress ``POINTS_CHALLENGE_COMPLETION`` Points Challenge Completion ``SMS_NUMBER_CHANGE_EVENT_OPT_OUT`` Sms Number Change Event Opt Out ``AUTO_RECHARGE_FAILURE`` Auto Recharge Failure ``AUTO_RECHARGE_DISABLE`` Auto Recharge Disable ``REST_MESSAGING_MARKETING`` REST Messaging Marketing .. _target_type: ``targetType`` Values ~~~~~~~~~~~~~~~~~~~~~ ``USER`` User ``SOCIAL_GROUP`` Social Group ``FACEBOOK`` Facebook ``TWITTER`` Twitter ``EMAIL`` Email Reply Objects ------------- .. http:jsonentity:: Message :jsonparam Long code: *(required)* The unique code of this message. :jsonparam String message: *(required)* The text of the message. :jsonparam String sourceType: *(required)* The source of the message. Indicates the application or user which generated the message. See :ref:`source_type`. :jsonparam String senderName: *(required)* If available, this is the name of the user who was the source of the message. :jsonparam String senderAvatarCode: *(required)* If available, this is the avatar code of the user who was the source of the message. :jsonparam String contextType: *(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 :ref:`message_context_type`. :jsonparam String contextCode: *(required)* If available, this is a code value specified by the ``contextType``. :jsonparam String contextLabel: *(required)* If available, this is a short label describing the item specified by the code. :jsonparam String contextDescription: *(required)* If available, this is a long description describing the item specified by the code. :jsonparam String contextImageCode: *(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. :jsonparam String contextLink: *(required)* If available, this is a URL for a page describing the item specified by the code. :jsonparam String contextLinkLabel: *(required)* If available, this is the label for the contextLink. :jsonparam Date date: *(required)* The date that this message was created. :jsonparam String pullImageLink: *(optional)* If available, this is a CDN URL for an image associated with this message. 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 | +-----------------------------------+----------------------------+