Automatically send invitation texts to referred survey respondents

[tinok]

For the online version of this survey we need to send invitations to mobile phone users asking them to take the Enketo survey. Same as in the phone survey, we need to already copy in the ID number of the referring respondent and the referee (newly created respondent) ID.

For this we need a new script that sends out the unique interview URLs directly to respondents via the WhatsApp API. Ideally, messages would only be sent via Whatsapp, not text.

See message content here.

This would require the script to attribute a unique respondent ID (which is currently done by Airtable for the phone survey), e.g. https://ee.kobotoolbox.org/single/7TmKR9nc?d[/aBwyGSiSsbZ6jGLMJ3G4vY/id_participant]=3&d[/aBwyGSiSsbZ6jGLMJ3G4vY/id_ref]=1

User flow:

1. Tino takes Enketo survey on his phone
2. He fills in three contact details (names, phone numbers) as part of the survey and submits to KoBo.
3. KoBo REST submission is made to new Heroku pipe, which triggers some kind of Twilio/Whatsapp script.
4. This script sends three Whatsapp messages with unique URLs, each containing a different respondent ID as well as Tino's original respondent ID.

[jnm]

@tinok, we need a message template to be prepared and sent to WhatsApp for approval:

WhatsApp requires that business-initiated notifications sent by your application be templated and pre-registered, with the exception of messages sent as a reply to a user-initiated message. … A WhatsApp message template is a message format that you can use over and over again to message users once they have opted-in and given your app permission to send them messages. To use a message template, you must first submit it to WhatsApp. WhatsApp reviews and approves each message template, typically in 48 hours or less, to maintain high-quality content and avoid spam in the ecosystem. Once WhatsApp has approved your template, you can use the templated message to send notifications.

Templates are the only game in town except for "session messages," but such a "session" only "starts when a user sends your application a message, and lasts for 24 hours from the most recently received message."

https://www.twilio.com/whatsapp/pricing/us https://developers.facebook.com/docs/whatsapp/message-templates/creation

[tinok]

Agree, session messages wouldn't work for us.

It seems like the "interactive message" template makes most sense for us to combine an image and a button to take the survey.

Our message would be an image and a button: Button: [Empezar la encuesta](unique url)

See the bottom of https://developers.facebook.com/docs/whatsapp/api/messages/message-templates/interactive-message-templates/examples. Their example shows that it's possible to include "localized" parameters in the URL, which in our case would be the id_ref and the id_participant. This is the URL that's currently generated by Airtable using both of these parameters:

https://ee.kobotoolbox.org/single/YYX3vn91?d[/amzW7EA68wdrETSoWkabsE/id_participant]=24&d[/amzW7EA68wdrETSoWkabsE/id_ref]=22

which is based on this formula in Airtable:

'https://ee.kobotoolbox.org/single/3YLSL2Z2?' 
&
'd[/aMsS69WLkVzNAcCsLyt7TC/id_participant]='
& 
{ID del participante}
&
'&d[/aMsS69WLkVzNAcCsLyt7TC/id_ref]='
& 
{Reclutado por}

So in Whatsapp this could be

https://ee.kobotoolbox.org/single/YYX3vn91?d[/amzW7EA68wdrETSoWkabsE/id_participant]={{1}}&d[/amzW7EA68wdrETSoWkabsE/id_ref]={{2}}

where {{1}} is the participant ID and {{2}} is the ref ID; or we just use the URL generated by Airtable to reduce the number of queries...

[jnm]

Tino is working on getting a facebook business manager account and a whatsapp business account for this (former is a prerequisite for the latter).

We're proceeding with developing this notification system with an abstract messaging backend so that we can use SMS/MMS/WhatsApp, whatever.

[dorey]

Also moved to https://github.com/kobotoolbox/bogo