Messaging Notifications - global-121/121-platform GitHub Wiki

Messaging / Notifications

  • Messages can be modified with the "notifications" endpoints
  • There is a json object for every message, per type and language
  • Messages can be send automatically in the 121 platform, or linked to certain actions
    • This is set through the type of the message
    • The following message types are linked to the corresponding action:
Topic Type Explanation Should be Twilio approved Example
Generic messages whatsappGenericMessage Generic message approved by Twilio, so that we can send any other not approved message to the PA afterwards yes There is a message waiting for you. Please reply "yes" to this message to receive it. Kind regards, Red Cross
whatsappReply Message send when a phone number that's registered in 121 doesn't have anything waiting (so no messages or vouchers) and sends us a message yes This is an automated message. Be aware, you cannot reply to this message. Questions? Please call XXX. Kind regards, Red Cross
whatsapp-default-reply Message send when an unknown phone number sends us a message (only necessary to set up this message for language "en", as there's no possibility to check in which language this should be send) yes This is an automated message. Questions? Please contact XXX. Kind regards, Red Cross
Status change included Message (optionally) send during action of inclusion of PA no Dear {{fullName}}, we would like to inform you that you have been included in the CVA program of the Red Cross. Within a week, you will receive more information. You will receive {{maxPayments}} payments.\n\nQuestions? Please contact XXX.\nKind regards, Red Cross
paused Message (optionally) send during action of pausing of PA no Dear {{fullName}}, we have paused your weekly payments. Please contact XXX for more information.\nKind regards, Red Cross
Visa messages visaDebitCardCreated Message send after PAs first payment with Visa, thus the Visa card will be created no Hello, we have sent your Visa card by post. You will receive it within 2 weeks. Once you receive the Visa card:\n- Activate your card\n- After activating your card there will be €[1](/global-121/121-platform/wiki/1) on your Visa card.\n- Every week we will put money on your card. Be aware, only if your card is activated.\n\nQuestions? Please contact XXX\n\nKind regards, Red Cross
visaLoad Message send after Visa card has been loaded, thus a PA with FSP Visa received a payment and has already a card no Hello, we have put new money on your card: €[1](/global-121/121-platform/wiki/1). Spend the money on the Visa card before the end of the month.\nBefore using the card, please check the balance here: XXX.\n\nQuestions? Please contact XXX\n\nKind regards,\nThe Red Cross
reissueVisaCard Message send after a Visa card has been reissued for a PA no Hello, you have indicated that you need a new Visa card. We have sent a new card to you. You will receive it within three weeks. Your old card has been blocked. The amount on that card will be available on your new card. This amount will be available after you activate the new Visa card. Kind regards, Red Cross
blockVisaCard Message send ater a Visa card has been blocked no Hello, your Visa card has been blocked. If you do not know why, please contact XXX. Kind regards, the Red Cross
unblockVisaCard Message send after a Visa card has been unblocked no Hello, your Visa card has been unblocked. You can use the card again. Questions? Contact XXX. Kind regards, the Red Cross
Albert Heijn messages whatsappPayment Message that the AH voucher is ready to be send, PA should respond with 'yes' to receive it yes Hello, we are ready to send you your Albert Heijn Voucher on Whatsapp. Answer 'yes' to this message to receive your voucher.\nKind regards, Red Cross
whatsappVoucher Message with the actual AH voucher no Hello, with this message you receive:\n- Your Albert Heijn Voucher (the image with the barcode)\n- Click XXX to see how to use your AH voucher\n\nThe grocery voucher is worth €[amount](/global-121/121-platform/wiki/amount). You can use the grocery voucher in all Albert Heijn supermarkets in the Netherlands and in Belgium. You can use the grocery voucher multiple times, as long as there is money left on it.\n\nQuestions? Please contact XXX\n\nKind regards, Red Cross
paymentInstructions Message send together with the message "whatsappVoucher", which only includes a PNG picture (Intersolve voucher instructions image), used to send payment instructions to the PA no image Important! This is not a message template that can be updated through the notifications API endpoint, but should be updated through the following one: /api/programs/{programId}/fsps/intersolve-voucher/instructions, where you can update the payment instructions picture that is sent to the PA
paymentReminder Message used only for AH Vouchers, a daily reminder for PAs who did not collect their vouchers yet. The reminder is sent for 3 days and then stops (as not to spam) no No example yet
  • Example of how message sending works when updating a status:
    • image
  • Changing a PA to these statuses does not have the option to send a message or send an automated message:
  • There is the possibility to add message templates with other "types", this could be handy if the program team wants to manually send a certain message multiple times (eg. over time). Then, this message can be implemented as a "templated" message in 121, that can be send manually.
    • The message can be send as follows:
      • Do the action "Send message to PAs", click on "Custom Message", the list of "templated" messages that can be send manually is shown
      • image
    • Make sure that isSendMessageTemplate is set to true (check below).
  • There is the possibility of adding placeholders to a message:
    • General placeholders (of fields in program) can only be used in messages send through status update or custom messages - so NOT in payment messages.
      • This should be done as follows: {{field}}, where field is the internal name of the field you would like to have as placeholder.
      • Review which placeholders you can use by starting to send a custom message to a PA and checking which fields can be added, there you can also review the internal name of that field
    • Placeholders of amount in payment messages should be done as follows:
      • for visaDebitCardCreated, visaLoad and jumboCardSent: [1](/global-121/121-platform/wiki/1)
      • for whatsappVoucher: [amount](/global-121/121-platform/wiki/amount)
      • eg: The grocery voucher is worth €[amount](/global-121/121-platform/wiki/amount).
  • Besides the type, language and message itself, the json object contains the following:
    • label: The label of the message template, which shows in the list of "templated messages" options when sending a message manually.
      • NB: If this label should be multiple languages (because the portal can be used in different languages), ALL message templates in the json with that type should have ALL languages in the label, regardless of the actual language of that message.
      • Eg: image
    • isWhatsappTemplate: If this is set to true, the message will be send immediately, without first sending the whatsappGenericMessage. Thus, this can only be done with messages that are actually approved by Twilio. NB: This is not working yet!
      • NB: Make sure that all messages with a type for which isWhatsappTemplate should be true (see table above) are actually approved by Twilio! Take this into account when updating message templates.
    • isSendMessageTemplate: If this is set to true, the message will show as an option in the list of "templated messages" when sending a message manually. See the picture above. It is possible to set this to true for messages with a type that is linked to a certain action in 121.
  • If a templated message is send to a person with a preferred language for which the template does not exist, the message will be send in English. If English does not exist, an empty message will be send.