Step by Step Summary

1. Get Business manager verified and setup a new app in the Developer portal
2. Add WhatsApp as a product in your new app in Developers portal
3. Setup a number in section 5 of “API Setup” in the developers portal
4. Add configuration keys - Callback URL and Verify token in the Configuration section
5. In the “Webhook fields” section directly below, press the “Manage” button and click ALL the tickboxes in “Subscribe” column
6. Add payment method in Meta Business Manager
7. Generate System User token
   • 1. In Business Manager, create an Asset with “Manage App” under Full control
     2. Generate token - Select “Never” for token expiration and tick the following boxes
     3. 1.  Business Management
        2.  WhatsApp business messaging
        3.  WhatsApp Business management
     4. Copy token and send to Yazi
8. Copy Phone number ID and WhatsApp Business Account ID in API setup in the developers Portal and send to Yazi
9. Toggle Developer mode to be on Live

https://app.tango.us/app/embed/Navigating-Research-Surveys-and-Configuring-WhatsApp-Manager---Meta-for-Developers-fc2a3edc11a344e4aef9643ca3780e2f

META FOR DEVELOPERS

1. Setup Developer Portal

1.1 Create an app

Go to Meta for Developers and click “Create App”  

1. Select “Other” for “What do you want the app to do?”
2. Select “Business” for “Select an app type”
3. Give your app a name, add a contact email and associate it with a Meta Business Manager

https://developers.facebook.com/apps/

Business Manager Verification in Meta Settings.

Now you will be eligible to verify your Facebook Business Manager. Verify your business Manager by uploading your company documents to prove that you are a legitimate company.

Meta article about this here: https://www.facebook.com/business/help/2058515294227817?id=180505742745347

Verification docs

These documents should validate the legal name of your business and your business’s official mailing address or phone number

Accepted document types

The primary document types that are acceptable for business verification are as follows. Make sure these documents are not expired and are issued by the relevant authorities.

• Certificate/Articles of Incorporation
• Business Registration or License Document
• Government Issued Business Tax Document: This could include a Tax Certificate. Self-filed tax documents are not accepted.
• Business Bank Statement
• Utility Bill: A utility bill is accepted only for Business Address and Phone number. The Legal Business Name must be on the utility bill. A utility bill is not an acceptable document for Legal Business Name verification

https://business.facebook.com/settings/info?business_id=

1.2 Create WhatsApp product

1. Click “Add Product”
2. Scroll down to WhatsApp and click “Set Up”
3. Press “Continue” in Quick start

2. API Setup

2.1 Add phone number

1. Click on “Add phone number” button in “Step 5: Add a phone number section”. Fill out your profile name and add the number:
2. 1. Add profile display name prescribed by Meta. Make sure it’s associated with you business’s actual name. If it is not associated, Meta is likely to reject. For Research bots, we typically advise [business_name] + Research as your Display Name. See Display Name Guidelines article for more details.
   2. Choose category and business Description
   3. Add number: Select country code and add number to receive OTP via SMS or phone call to verify

Note:

Make sure you have the number ready to receive SMS or phone call

After adding your number, you might need to refresh the page if the number isn’t showing up

2.2 Setup Webhook

Go to the Configuration section and press “Edit” button in the webhook card section

1. Enter Callback URL and Verify token (both of these keys will be provided to you by Yazi)
2. Press “Verify and Save” button (it will do a pink test and automatically save)

In the “Webhook fields” section directly below, press the “Manage” button

1. Click ALL TICKBOXES in Subscribe column. This allows us to track and retrieve the data so make sure to tick every one!

META BUSINESS MANAGER

3. Add payment method

In order for the WhatsApp account to activate, you need to add a card or payment method.

1. Go to your Meta Business Manager to setup and select:
2. 1. WhatsApp Accounts
   2. Click on the new WA account
   3. Settings
   4. Payment Settings

4. System User token

You have now entered what the identification that WhatsApp needs from our software system. Now, for our system to connect to your number, we need 3 items or identifiers from you. These are:

1. System User token
2. Phone number ID
3. WhatsApp Business Account ID

4.1 Add System User if none existed

Head back to Business Manager to generate a system token from someone who is a System user:

Go to Users and click on “System Users” (you need to be an Admin user to do this)

Note:

If no System user exists, Press the “Add” button → Set system user role to Admin

Difference between system user and regular user. System user doesn’t require a reset of the token after it expires because the system can be setup as permanent. If system is compromised then you can revoke

4.2 Add Asset

Click “Add Assets” and a Modal will pop up. Navigate the following:

1. Click the “Apps” page
2. Select your app you just created
3. Toggle “Manage App” under Full control to be on
4. Press “Save changes” button

4.3 Generate Token

1. Click “Generate Token”
2. Select your App
3. Select “Never” for token expiration

Tick the following boxes

•  Business Management
•  WhatsApp business messaging
•  WhatsApp Business management

When you've done this, Click “Generate Token” button

Note:

This is the identifier that will be sent back to Yazi to configure the system to your personal account. Once the code is generated, you can send it to Yazi to complete the configuration of your account

Selecting Never for Token expiration means you don’t have to keep configuring new tokens

META FOR DEVELOPERS

4.4 Access Token via Debugger

To copy or access the information about the token: Go to Access token page in Tools in the Facebook Developers portal https://developers.facebook.com/tools/accesstoken/

1. Click “Debug” on the app you just created
2. Copy the Debug code

Note: Also see all the information about the token

5. Copy Phone number ID and WhatsApp Business Account ID

Go back to API setup in the developers Portal

Copy the following:

1. Phone number ID
2. WhatsApp Business Account ID
3. The actual WhatsApp number

Send these back to Yazi along with the System token

6. Toggle App Mode onto Live

Toggle the app to “Live”. As this is approved, you will normally be upgraded to be able to send 1,000 Template messages per day (1,000 outbound notification messages per 24 hours)

Note: You may need to add your Privacy policy in Basic Settings to be able to do this.

Might take a day to populate.

Additional profile check

1. Check status of number
2. 1. Should take 1-2 business days to be approved
3. Profile
4. 1. Add description
   2. Picture

Steps to launching a Survey

Yazi’s Web app

💎 NB Summary 💎

1. Title =Starter Phrase. The survey or campaign title is the phrase that will become the starter phrase in WhatsApp. I.e. if the title is ‘Eat healthy study’, sending ‘Eat healthy study’ to the WhatsApp bot will take you to the beginning of the survey (once the survey is launched).
2. Manually Save. Progress needs to be saved manually by clicking the orange save button.
3. Title under 24 Characters. Keep the title to under 24 characters so that the title can be a button in your Template message that invites people to participate in survey. Template message buttons are limited to 24 characters.
4. Formatting for WhatsApp.
5. 1. No ‘ordering’ questions
   2. No ‘grids’ - multiple choice or tickbox grids
   3. Do not use commas in multi-select options
   4. A multiple choice option answer can't be more than 50 characters

Yazi has a webapp that comprises of 5 key components:

1. Dashboard

See all survey campaigns created for a particular workspace

2. Specify audience

Choose demographics of audience you’d like to target. These demographic attributes are connected to the attributes in the signup

• 1. Number of participants/respondents
  2. Country
  3. Age
  4. Gender
  5. Occupation
  6. Education
  7. Number Children

3. Create survey

Similar interface to Google forms or SurveyMonkey.

• 1. Types of questions: Single-select and multi-select multiple choice, Open text, Image/Video/Voice note
  2. 1. For multi-select:
     2. 1. Add this text to your question to show how they must answer: Select all that apply by giving the letters separated by comma (e.g. a, c, d)
        2. Don’t use commas in Answer options. The data for multi-select answers comes back as a string in a single cell with the answers separated by comma. Therefore, for Q16, you might have this answer: Basic essentials (such as food, housing, clothing), Leisure & entertainment (such as travel and media). This makes it very tricky for software to pickup which are separate answers and which are commas as part of answers. So, rather use a semicolon to separate list items.
  3. ‘Other’ question toggle which automatically asks ‘Which other/s?’ if the other toggle is selected
  4. Logic: Can skip or jump participants to certain parts of the survey or flow using logic in single-select multiple choice questions

4. Launch

Review the questions and audience selection. Once happy, launch the survey by selecting the invoice option and giving your email. The pricing listed here will not apply to you, as it is for the case in which Yazi provides the audience. A Yazi team member will then

5. Results

Bar graph of each response with ability to filter and select using both other questions and demographic information

NB: Product notes

1. Progress is not saved automatically, remember to save with the button
2. The webapp does not currently support ‘multi-player’ teams. One set of login details can thus be shared and used
3. Use the text format for a: voice note, Picture or video question
4. Pricing is calculated automatically for basic audience selections where Yazi recruits the audience. However, it is likely to change based on target quotas and incidence rates.

Question text

A question or message sent to a respondent in the bot can't be more than 500 characters

To explain something to a respondent (where you do not want it to be a question): Make it a Multiple Choice question and put 'Continue' or 'Understood' as the answer

Multiple choice

A multiple-choice option answer can't be more than 50 characters (Meta limit)

1-24 character multiple choice options appear as buttons

• 1 - 3 options appear as buttons in the chat
• 4 - 10 options appear in a burger menu show up as options when clicked

A question where 1 of the multiple choice options is 25-50 characters OR, if there are more than 10 answer options will appear with letters as the answer e.g. Option 1 is A, Option 2 is B etc

Multi-Select Multiple choice

Do not use commas in multi-select options as our system detects separate options by commas ❌

2. Submitting & managing Template messages

💎 NB Summary 💎

1. Button = Starter phrase. The button must be equal to the starter phrase that relates to the survey you are using the Template to invite people to. Add a ‘Custom’ Button to do this.
2. Type of Template: For survey invitations, select the Marketing type. For payment notifications, select the Utility type. Utility is cheaper than
3. Dynamic placeholders. To personalise the message, insert dynamic placeholders into the message e.g. {{1}}. They can only be inserted in the body of the message → We only support dynamic fields in the body.

Meta WhatsApp portal

A WhatsApp template message is a pre-formatted message that can be used to send information or updates to a group of people quickly. It is a specific message format that companies can use to send standardised notifications, such as purchase confirmations, delivery alerts, etc. 56. Unlike free-form messages, template messages are used to open marketing, utility, and authentication conversations with customers1. To use WhatsApp message templates, brands must jot down the desired message, save it as a template, and then select and customise it before sending it to the recipients2. Here are some guidelines to follow when creating WhatsApp message templates:

• Naming of template: The name of your message template can only contain lowercase alphanumeric and underscores (e.g. account_update_1) 5.
• Size of template: The message has a limitation of 1024 characters and cannot include new lines or line breaks5.
• Personalisation: Brands can personalise WhatsApp message templates with customisable placeholders, media headers, and Quick Reply or Call-to-Action buttons3.
• Approval: WhatsApp message templates must be submitted to WhatsApp for approval before use3.

This is where template messages are submitted for approval. Dynamic variables can be added to template messages so that the notification that is sent can be dynamic and personalised.

1. In the WhatsApp Manager, mouseover the suitcase icon (Account tools) and click "Message template
2. Click "Create Template" and select the type of template you want to create1.
3. 1. For survey invitations, select the Marketing type.
   2. For payment notifications, select the Utility type. Utility is cheaper than
4. Fill in the required fields for the template, such as the template name, category, and message body.
5. You can also add placeholders to your message body to personalise the message for each recipient.
6. Add
7. Once you have created your template, you can use it to send messages to your customers.

Templates typically take 1-3 days to be approved.

Add a footer: Opt-out from these messages anytime from the main menu

Choose a Custom button

Message Analytics

Turn on message tracking so that you can get an analysis of the results

It also shows usage, conversations and engagement with the bot in a dashboard

Meta Costing Notes  

• WhatsApp messaging costs will be billed to your company directly via your  Meta Business Manager. This is subject to change according to Meta  WhatsApp pricing.  
• WhatsApp charge per conversation, not per individual message.  Conversations are 24-hour message threads between you and your  customers. They are opened when messages you send to customers are  delivered.  
• WhatsApp pricing is in USD and at the current exchange rate, the costing is as  below:

3. Recruiting participants to the survey (inviting them in):

💎 NB Summary 💎

1. Matching up columns with variables in Template. Make sure your CSV lines up with the dynamic variables you created in the Template message in Meta.

Now the survey is live in the bot but it needs to be accessed by the participants. Participants can access surveys in 2 ways:

1. Notification or Template message. Client can upload a list of contacts to bulk message app and send those people a ‘Template’ message in WhatsApp inviting them to participate in the research.
2. Survey menu on WhatsApp. Only participants who meet the required demographics will qualify for the survey.
3. Create WhatsApp link with starter phrase. Recruit people to study by generating a custom link to the study in WhatsApp that, when clicked, will open WhatsApp to your number and populate the WhatsApp text box with the Starter phrase for the survey. Once they send it, it will take them to the beginning of the survey in the client’s WhatsApp bot number. I.e send WhatsApp link to people in SMS, Facebook Messenger, Email or digital ads with link as button.

The Rather Chat app (explained below) enables template messages or notifications to be sent to participants, inviting them to do the survey.

1. Notification or Template Messages

To send a notification or Template messages:

1. Submit Template message to Meta with starter phrase as button
2. Create the Template message layout with external_id and var1 & var2 etc. depending on Template message body
3. Download a CSV of contacts you want to message: Cell number + dynamic variables in columns that coincide with Template message structure
4. Go to Rather Chat app and select Triggers
5. Create a new broadcast by selecting the template you want to send (pulls from Meta), uploading the contact list CSV and pressing Create!

Format of CSV for Template Message

The information in the CSV document must be arranged to match the WhatsApp Template message it is going to be used on.

External_id → Cell number (must contain country code)

var1 → First variable placeholder ( {{1}} )

var2 → Second variable placeholder ( {{1}} )

Note:

• Template message will fail if duplicate cell numbers are sent
• Dynamic Variables cannot be used in buttons as the Rather Chat app doesn’t support them

• Dynamic link using UTM parameters in URL

• Child books 136 takes respondent to survey - starter phrase

2. Survey menu on WhatsApp

Survey will be available to people to access and complete in the survey menu if they meet the survey’s demographic requirements

4. WhatsApp message blast (‘Bulk SMS’) & Agent chat:

💎 NB Summary 💎

1. Send bulk message.
2. 1. Navigate to ‘Triggers’,
   2. Create a new trigger
   3. Choose the Template you want to send
   4. Upload the CSV
   5. Send it
   6. See delivery and read-rate analytics (after 1-3 min)

Rather Chat app

1. Send template messages to participants by uploading a CSV of cell numbers to send using the a pre-approved Template message from Meta
2. See chat history from last 24 hours (see below screenshot). A Rather Chat user can send a message to a participant as the bot in this chat
3. See bots or flows running + Team members + Channels/Numbers (if different cell numbers connected to FB account)

Conversation inbox manager → ‘Chats’

See full conversation histories with participants. You can only send a message to a participant if they have sent a message to your bot in the last 24 hours. Otherwise, communication needs to be triggered through a Template message.

If you send a message to a participant as an ‘agent’, they will receive it as a normal message but not be directed to any other point in the flow. Thus, the participant’s response will be saved as a question variable if the last message sent was a question from your bot to that participant.

Notes

1. Tag participants in inbox to be able to easily filter and lookup groups of participants
2. Search participants by number in search bar

Template Message → “Triggers”

Paying Participants

Only applicable if using Yazi’s participant incentive management system

• Payment methods currently supported through API:
• • Reloadly - Airtime payments to Rest of Africa
  • 6DOT50 - Aggregator voucher currency to South Africans
• Set amount in local currency

Format of Payment CSV

• Column A: userId → User ID of participant
• Column B: amount → amount in local currency (E.g. ZAR if SA or Ksh if Kenyan)
• Column C: status → Pass or Fail
• Column D: survey → Survey ID
• Column E: referral balance → Referral amount in local currency

How to pay

1. Send ‘Admin portal’ in WhatsApp
2. Select ‘Pay Users’
3. Upload CSV in WhatsApp

Example Run Through

1. Launch survey in Yazi webapp

Launch Survey called: Child books 136

2. Submit Template message : Meta

Set reply button as survey title

Header → Text

New Survey

Body

Hey {{1}} 👋
It's AI-BO Surveys here - this is our new number (Yazi Research)!

We have a quick survey opportunity for you:

Time: *2 min* ⏰
Reward: *R10* 💸

Just press *Child books 136* to begin.

Footer

Opt-out from these messages anytime from the main menu

Quick reply

Button 1: Child books 136

Button 2: Main menu

3. Create CSV to send to : Sheets example

The template only has one variable and it is for the participant’s name so we only need 2 columns. Download file as a CSV.

👉 Get Google Sheet example here

4. Send Template message in Rather Chat

‍