WhatsApp notifications - rodekruis/IBF-system GitHub Wiki

IBF allows to send WhatsApp notifications

• for trigger/warning alerts, so equivalent to email notifications
• for new community notifications (see guide on community notfications) have a community_notifications layer which can be filled via a specific Kobo-form. The Kobo instances used by 510's IBF-system can be found in the internal Tech Doc. This guide allows how to set this up and work with it.

---

1. Twilio setup
2. Test sending WhatsApp message from local API with Twilio WhatsApp sandbox
3. Test sending WhatsApp message from test/demo API with Twilio WhatsApp sandbox

---

IBF uses Twilio for sending WhatsApp messages.

• Set up Twilio IBF-platform account
• Create a messaging service
• Create message templates of which the text aligns with notification-info.json, and copy the right contentSids.
• In local .env update from that messaging service
  • TWILIO_SID
  • TWILIO_AUTHTOKEN
  • TWILIO_MESSAGING_SID
• and update TWILIO_WHATSAPP_NUMBER = +14155238886 (the standard Twilio whatsapp sandbox number)

1. Set up ngrok to facilitate incoming messages. Since the initial WhatsApp message can be a validated template only, it cannot contain much specifics. Therefore it contains basic info and an invitation to reply 'yes'. Upon that 'yes' a 2nd message with more details is sent. (NOTE: this is only needed for trigger/warning notifications, not for community notifications, which do not come with incoming messages.)
   • Use ngrok to mock an external API service:
   • Sign up on ngrok using your GitHub account
   • Download the executable
   • Add the folder to the system environment variables
   • Add the authtoken using the command provided in the download page, ngrok config add-authtoken <token>
   • Run ngrok on port 3000, ngrok http 3000
   • You can find the URL of your API in the Forwarding field. Copy this:
     • As value for the EXTERNAL_API_SERVICE_URL field in the .env file in the root folder
     • In the WhatsApp sandbox settings (go to right subaccount > Develop > Messaging > Settings > Whatsapp sandbox settings) as:
       • <EXTERNAL_API_SERVICE_URL>/api/notifications/whatsapp/incoming in the WHEN A MESSAGE COMES IN field
       • <EXTERNAL_API_SERVICE_URL>/api/notifications/whatsapp/status in the STATUS CALLBACK URL field
   • Rebuild the service with docker compose -d up ibf-api-service

2. Add your WhatsApp phone number to the WhatsApp sandbox by texting the code provided in the subaccount to the sandbox phone number as found in Twilio
3. Create a new IBF-user through API with your WhatsApp phone number and assigned to the country and disaster-type you are testing for
4. Send a whatsapp
   • for a trigger/warning notification (for a country/disasterType with an active trigger) via the POST /api/notification/send endpoint.
   • for a community notification via the POST /api/point-data/community-notification endpoint
5. You should receive the initial message. And upon a reply you should receive the follow-up message. Note that the initial message will arrive anyway, also if you did not set the above callback URLs correctly.

1. Ngrok is not needed, instead the EXTERNAL_API_SERVICE_URL is simply the server URL itself, e.g. https://ibf-test.510.global/.

2. Set the Twilio callback URLs to the right environment (ibf-test or ibf-demo). If e.g. ibf-test, that would be:

   • In the WhatsApp sandbox settings (go to right subaccount > Develop > Messaging > Settings > Whatsapp sandbox settings)
   • https://ibf-test.510.global/api/notifications/whatsapp/incoming in the WHEN A MESSAGE COMES IN field
   • https://ibf-test.510.global/api/notifications/whatsapp/status in the STATUS CALLBACK URL field

For the rest, follow the same instructions as above to receive initial and follow-up messages.