Setting up the Whats App API #

To get Yoto Messenger running you need a Whats App API token which can you can get started with for free.

Create a Facebook account #

The first step is having a Facebook account which will allow you to complete the next steps to getting a Developer account.

Create Meta Developer Account #

While logged into your Facebook account, head over to https://developers.facebook.com/docs/development/register and create your Meta Developer Account.

Create your App #

Once you've been verified you can now create your 'app'.

Head to https://developers.facebook.com/apps/ and click the Create App button.

  • App Details: Enter a name for your app (this can be anything) and your email address.

  • Use cases: On this step you need to select Other to allow us to access the Whats App API.

  • App Type: Here we should select Business.

  • Details: The final step should just be a summary of the details we've entered and you can click Create App to complete.

Add Products #

After clicking Create App you will then be taken to a screen asking to Add products to your app. Here we will click the Setup button beside WhatsApp.

On the next screen, select a Business Portfolio (usually you just want to keep the default) and hit Continue.

Set up API #

After that you should get to a Quickstart screen with a blue button at the top named Start using the API, either click that, or click the API Setup item on the left menu.

From this page you can generate an Access Token which you can then use in your .env file. Click the blue Generate access token button, go through the auth process that follows and then copy/paste the code that is given. It should be used in the WHATS_APP_AUTH_TOKEN key.

*** Note that this token will expire every 23 hours so will have to be re-generated after this period. See the Permanent WhatsApp API Token section below for details on how to create a token that won't expire.

Copy Your Phone Number ID #

You will notice that you are given a 'Test Number' which is the phone number that your messages will be sent from, and the Yoto Messenger members will send voice notes to.

This phone number comes with a Phone Number ID (displayed below the number) which you should copy/paste into the .env file as the WHATS_APP_PHONE_NUMBER_ID

Whitelist your Phone Number #

When in test mode you can register 5 phone numbers that are able to send and receive messages from the WhatsApp API. On this screen there is a To: dropdown field. Expand this and click the Manage phone number list button at the bottom of the list. From here you can add/remove the phone numbers you want to whitelist.

Note that the owners of these phone numbers need to provide a verification code that is messaged to them. So be ready to get them to forward it to you.

Setup WhatsApp Web Hook #

When a message is sent to your WhatsApp number we want it to hit our API via a webhook.

To set this up click the Configuration link on the left menu (under the WhatsApp heading).

On this page we need to enter our API's endpoint that we want to get hit when a message is received. You will need your API to be running on a public domain.

This value should be https://<YOUR-DOMAIN-HERE>/whatsapp

In the Verify Token field you can enter any string. This string should match the WHATS_APP_WEBHOOK_VERIFY_TOKEN value in your .env file.

Click the Verify & Save button and, all being well, it should work fine.

Subscribe to Messages #

Once that is saved and verified we need to listen for messages.

In the Webhook fields section subscribe to the messages item so we are notified of new messages.

Complete! #

With all these steps complete you should be ready to send and receive messages with the WhatsApp API.

Permanent WhatsApp API Token #

The token we have created will expire after 23 hours so to avoid this we can create a permanent one. To do this follow the steps below:

  • From the WhatsApp API configuration screen, go to the Business Settings section via the hamburger menu.
  • Click System Users in the menu left menu.
  • Click the admin user in the list.
  • Towards the top right you should see a Generate Token button.
  • Click this and follow the steps in the wizard, selecting the correct App, the expiry to never and the permissions to include whatsapp_business_management and whatsapp_business_messaging.

Whats App Templates #

Yoto Messenger relies on predefined templates to send to users are various stages of the app's process. You can create these templates in the WhatsApp Manager.

These can be created as Custom Marketing Messages and should be set to use English (US) with the matching template name as below.

Name: account_owner_voice_message_success_2

{{member_name}} has sent your family a voice message via Yoto Messenger!

Open the Yoto app and have a listen!

Name: unknown_account

Unfortunately your number isn't linked to a Yoto Messenger Account.

Please contact the person who would have created the account and ask them to check your number.

Name: voice_message_failure_2

Unfortunately something went wrong while trying to save your voice note.

If you would like to resend the message, simply "forward" the message to this number and it will be resent.

Name: unknown_sender

Unfortunately, your number isn't registered with any Yoto Messenger accounts.

Please contact the account holder to ensure your number has been entered correctly.

Name: new_account_holder_member

Hi {{account_holder_name}},

Thanks for signing up to Yoto Messenger!

You can now add family members to your account, allowing them to send voice notes directly to your Yotos.

Or if you'd like to try it out yourself, just reply to this message with a voice note and it will be uploaded to a new playlist (Yoto Messenger) in your account.

For more information on how it all works, check out the link below.

Name: new_member_welcome_2

Hi {{member_name}},

{{account_holder_name}} wants you to send voice messages to their family's Yoto!

Simply reply with a Voice Note and it will be sent to their Yotos. 

For more information about how this works, visit the link below.

Name: voice_message_success

Thank you for your voice message! It was delivered successfully.

If you would like to send another just send another voice note to this number!

Name: emoji_message

You've been sent a message from {{account_holder_name}}'s Yoto:

{{emoji}}