How to use Yazi's WhatsApp bot and platform: A full guide with screenshots

Yazi’s platform comprises of 4 key components:


See all survey campaigns created for a particular workspace and create new campaigns.


Specify audience - Choose demographics of audience you’d like to target. The survey will only be sent to people who meet this criteria. If you want to target an audience using an attribute that is not present there, use the screener feature. 

The following are off-the-shelf selectors and attributes:

  • Number of participants/respondents
  • Country
  • Age
  • Gender
  • Occupation
  • Education
  • Children

Survey questions 

Create survey - Similar interface to Google forms or SurveyMonkey.

  • Types of questions: Single-select and multiselect multiple choice, Open text, Image/Video/Voice note
  • ‘Other’ question toggle which automatically asks ‘Which other/s?’ if other is selected
  • Logic: Can skip or jump participants to certain parts of the survey or flow using logic in single-select multiple choice questions

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


Notifying participants who qualify that there is a survey available for them

Participants can access surveys from the notification message or from the Survey menu on WhatsApp. Only participants who meet the required demographics will qualify for the survey.

Participants complete survey

Completing the survey in WhatsApp is very simple and looks like the screenshots below.

WhatsApp screens.png

Yazi’s bot in WhatsApp offers the following question types and collects the following data:

Voice Note: The voice note question type allows participants to respond to survey prompts by recording an audio clip.

Multiple Choice Questions: WhatsApp has recently introduced a powerful feature that enhances the user experience (UX) of surveys—the use of buttons. For 2-3 options, they are displayed as buttons in the chat (see below), while 4-10 options appear as a selectable list after you click a burger menu icon in the chat.

Image/Screenshot: With image/picture questions, participants can upload and share images or pictures as responses to survey prompts.

Video: The video question type enables participants to respond to survey prompts by recording and sending videos

Survey Data goes into database

Data quality Assessment process

We have a rigorous data checking process that uses AI and advanced data science techniques to identify anomalies and bad actors. We use the following assessment techniques:

  1. Speeding - A completion time that is too fast indicates the respondent has not sufficiently comprehended the questions
  2. Gibberish checker - Checking that open text answers are not “gibberish” and can be understood as a sentence
  3. Straight-lining checker - Checking that the sequence of answers does not follow the same pattern - e.g. A, A, A, A, A, A
  4. Red herring question - Intentionally placing “oddball” questions into the survey to see if the respondent was paying attention.
  5. Evidence question - Where we specifically need an audience that exhibits a certain behaviour or matches a certain demographic, we ask respondents to send a picture that proves they match/meet requirement.
  6. Redundancy checks - Incorporate duplicate or similar questions to assess response consistency and identify careless or inconsistent respondents.
  7. Panel recalibration & assessment  - We recycle demographic and behavioural questions every 4 months to compare against historical answers.

We return some of the assessment information to the client in the CSV / Excel or Google Sheet that we give back.

Push into Excel/Google Sheet for client

Incentives & Paying participants

Yazi approaches  incentives based on the subject matter of the survey. If possible, the incentive will be aligned with the survey e.g. business services for business owner survey.

It utilises 3 incentive approaches:

  1. Completion reward
  2. Prizes (Lotto style)
  3. Entertainment/free - Complete to acquire information or see how they stack up against other respondents or population

Survey participants are paid in one of the following ways:

  • Airtime (for non-South African countries)
  • 6DOT50
  • EFT in participant’s bank account
  • Takealot voucher

How signing up to Yazi’s bot as a survey participant works

Data flows_ Web-app, Yazi & Comparisure - Bot layout for participants (1).jpg

Signup  and onboarding process which captures agree/disagree to data T&Cs and agree/disagree with opt-in’s to outbound communication (template messages). The following demographic questions are also asked

  • Country
  • Age / Date of Birth
  • Gender
  • Occupation
  • Education
  • Children
  • Race
  • Location / Postcode
  • Business owner
  • Languages spoken

Main Menu

  • Options in menu: Survey Menu, Opt-in / Opt-out, FAQs
  • Announcements bar containing any information Yazi wants to share

Survey Menu

  • Shows surveys that participants qualify for

Starter phrases

  • Starter phrases are specific text that, if sent to Yazi’s bot, will take participants to a specific flow. I.e. Main menu jumps people to main menu. Starter phrases are used in buttons so that if a button is clicked, the starter phrase is sent and jumps a participant to a point in the flow.

Survey access: Accessed in 2 ways

  • Starter phrase: The title of the survey in the JSON
  • Survey menu: Available to participants who qualify for the survey based on their demographic

Start your Research Journey in Emerging Markets today!

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
        1.  Business Management
        2.  WhatsApp business messaging
        3.  WhatsApp Business management
      3. 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


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
Screenshot 2023-09-06 at 09.02.37.png
Screenshot 2023-09-06 at 09.02.58.png
Screenshot 2023-09-06 at 09.03.20.png

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:

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

Screenshot 2023-09-06 at 09.04.14.png

1.2 Create WhatsApp product

  1. Click “Add Product”
  2. Scroll down to WhatsApp and click “Set Up”
  3. Press “Continue” in Quick start
Screenshot 2023-11-01 at 08.57.04.png
Screenshot 2023-11-01 at 08.43.03.png

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:
    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


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
Screenshot 2023-11-01 at 08.45.44.png
Screenshot 2023-11-01 at 08.43.37.png

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)
Screenshot 2023-10-31 at 12.33.35.png

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!
Screenshot 2023-10-31 at 11.36.50.png


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:
    1. WhatsApp Accounts
    2. Click on the new WA account
    3. Settings
    4. Payment Settings
Screenshot 2023-11-01 at 09.14.30.png

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:

Screenshot 2023-11-01 at 09.20.50.png

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


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
Screenshot 2023-11-01 at 09.28.28.png
Screenshot 2023-11-01 at 09.28.02.png

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


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
Screenshot 2023-11-01 at 09.33.28.png
Screenshot 2023-11-01 at 09.35.27.png
Screenshot 2023-11-01 at 09.41.32.png
Screenshot 2023-11-01 at 09.41.56.png


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

  1. Click “Debug” on the app you just created
  2. Copy the Debug code
Note: Also see all the information about the token
Screenshot 2023-11-01 at 09.50.13.png
Screenshot 2023-10-31 at 11.57.11.png

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

Screenshot 2023-11-01 at 09.54.49.png

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.

Screenshot 2023-11-01 at 09.57.59.png
Screenshot 2023-11-01 at 09.58.32.png

Might take a day to populate.

Screenshot 2023-10-31 at 12.13.03.png

Additional profile check

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

Steps to launching a Survey

Yazi’s Web app

Yazi Dollar based explainer deck copy.png

💎 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.
    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
      1. For multi-select:
        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.
    2. Other’ question toggle which automatically asks ‘Which other/s?’ if the other toggle is selected
    3. 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
Occupation demographic.png

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.
    1. For survey invitations, select the Marketing type.
    2. For payment notifications, select the Utility type. Utility is cheaper than
  3. Fill in the required fields for the template, such as the template name, category, and message body.
  4. You can also add placeholders to your message body to personalise the message for each recipient.
  5. Add
  6. 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.

Screenshot 2023-09-19 at 17.17.51.png

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

Screenshot 2023-09-19 at 17.15.06.png

Choose a Custom button

Screenshot 2023-09-14 at 09.56.23.png

Message Analytics

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

Screenshot 2023-09-14 at 09.57.57.png

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.

Screenshot 2023-09-14 at 09.56.59.png

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}} )


  • 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
Screenshot 2023-09-18 at 00.14.05.png
Screenshot 2023-09-18 at 00.16.07.png
  • Dynamic link using UTM parameters in URL
Screenshot 2023-09-18 at 00.17.47.png
Screenshot 2023-09-18 at 00.19.16.png
  • 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.
    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.

Screenshot 2023-05-19 at 12.08.46.png


  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”

Screenshot 2023-05-19 at 16.32.11.png
Screenshot 2023-09-18 at 00.45.07.png

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
Screenshot 2023-08-31 at 17.37.58.png
Screenshot 2023-08-31 at 17.38.46.png

Example Run Through

1. Launch survey in Yazi webapp

Launch Survey called: Child books 136

Screenshot 2023-09-19 at 17.09.33.png

2. Submit Template message : Meta

Set reply button as survey title

Screenshot 2023-09-19 at 17.13.01.png

Header → Text

New Survey


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.


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.

Screenshot 2023-09-19 at 17.30.40.png

👉 Get Google Sheet example here

4. Send Template message in Rather Chat

Screenshot 2023-09-19 at 17.41.34.png