Skip to content

Whatsapp notifications

Jump to bottom
jannisvisser edited this page Mar 31, 2025 · 4 revisions

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.

Table of Contents

  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

Twilio setup

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)

Test sending WhatsApp message from local API with Twilio WhatsApp sandbox

  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

Note

do not forget to put WhatsApp sandbox settings value back to its original value if you're using this same Twilio subaccount e.g. both for local testing and for remote test/demo environments

  1. 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
  2. Create a new IBF-user through API with your WhatsApp phone number and assigned to the country and disaster-type you are testing for
  3. 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
  4. 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.

Test sending WhatsApp message from test/demo API with Twilio WhatsApp sandbox

  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.

Clone this wiki locally