Messaging connection

The two accounts the group's messages are sent from: WhatsApp Business from Meta, and SMS from 4jawaly or Mora.

What it is for

The group's messages are sent from its own accounts, never MG Tech's. Here the two accounts' keys are saved, the connection tested, a test message sent, and the connection switched off. Notices go on WhatsApp by approved templates, and by SMS when WhatsApp is not linked; sign-in codes go on WhatsApp, then SMS; campaigns go on WhatsApp only. The group pays for all its messages — sign-in codes and campaigns included — to Meta and to its SMS provider directly; they are not part of SchoolOS's price, and MG Tech charges nothing for them.

Who uses it

The page opens for whoever holds “View the messaging connection”, to look only, or “Manage the messaging connection”, to work in it. In the built-in roles: Owner. They are granted to any role under Settings → Roles and permissions.

Step by step

1. On the WhatsApp card: paste the access token, the phone number ID, the WABA ID and the app secret, then “Save”.
2. At Meta, under WhatsApp → Configuration → Webhook: paste the callback URL into “Callback URL” and the verify token into “Verify token” with their “Copy” buttons, press “Verify and save”, then subscribe to the messages field.
3. Press “Test the connection”, then type a mobile number in the test message's field and press “Send a test message”; the answer shows in place.
4. On the SMS card: choose the provider, type its key and the sender name, then “Save”.
5. Under “SMS credit warning threshold” on the same card: type a number in the provider's own unit, as “Test the connection” shows the balance, then “Save the threshold”. The balance is read every morning, and below the threshold whoever manages the messaging connection is told in the bell, once a week while it stays low. An empty box warns nobody.
6. With Mora: copy the “delivery-report address” into the webhook settings of Mora's portal, so each message's delivery shows. The address is a secret: share it with no one.
7. Under “Links for your Meta app's settings”: copy the three links with their “Copy” buttons and paste them into your app's settings at Meta (App settings → Basic): “Privacy policy URL”, “Terms of Service URL”, and under “User data deletion” choose “Data deletion callback URL” and paste the data deletion link there: Meta calls it when someone asks Meta to delete their data from your app.

How it works

Keys are encrypted before they are stored, and only their last four characters show after saving; an empty box keeps the stored key, and changing the SMS provider replaces its keys. The access token is required on the first save only, and the two IDs are digits. “Test the connection” asks Meta for the number, its quality and its messaging limit, links the WhatsApp Business account to your app — without that link no delivery reports or replies arrive — and then points you to “Suggested templates to approve” under “WhatsApp templates”: none of them goes to Meta before you approve it. The test message exists on WhatsApp only: it goes to the number you type by SchoolOS's approved general template, the number is not kept, it never goes to a number whose chat is blocked or whose owner asked to stop messages, and an account sends five an hour at most. The webhook accepts only a call signed with the app secret (without one saved, a warning on the WhatsApp card tells every reader of the page), and so does the data deletion link when Meta calls it: it records the deletion request and answers Meta with a confirmation code and the link to the request's status page. “Switch off” stops the account and keeps its keys: notices and sign-in codes go by the other channel if it is linked, otherwise they are recorded as not sent; saving switches it back on. “Disconnect”, by contrast, deletes the account's saved keys and stops it, so it comes back only when the keys are entered anew; it is the owner's alone, with a code from the owner's authenticator app. The action log records which fields changed and the test's outcome, never a key, and of the test message's number only its last four digits. Only someone holding “Manage the messaging connection” changes it.

On the page

• WhatsApp Business: the keys, the connection's state, the test, the test message, and switching off.
• What the system last saw: Meta's check of the URL, the last event, the number's quality, and the messaging limit.
• The callback URL and the verify token, copied into your app's settings at Meta.
• A test message to a number you type, by SchoolOS's approved general template; the answer shows in place and the number is not kept.
• SMS: the provider, the keys, and the sender name.
• Once the number is connected: the suggested templates waiting for your approval, with the way to review them. None of them goes to Meta before you approve it.
• “Name in messages”: the group's name the WhatsApp templates close with, instead of the long legal name.
• The three links for your app's settings at Meta: privacy policy, terms of service and the data deletion link Meta calls, with copy buttons.

Part of these flows

• A WhatsApp campaign: one message to many

Questions

Delivery reports and replies don't arrive.

Save the app secret, paste the URL and token into Meta and subscribe, then press “Test the connection” so the account is linked to the app.

The test message says there is no template.

SchoolOS's general template is not approved yet: approve it under “Suggested templates to approve” in “WhatsApp templates” and wait for Meta's approval.

Meta refused the test message with code 131030.

The number is not on the list of recipients allowed: while your app is in development mode at Meta, its messages reach only numbers added to that list in your app's WhatsApp settings. Add the number there, or move the app to Live mode.

Who pays for the messages?

The group, to the providers directly: Meta bills for WhatsApp messages and the SMS provider for its own, each on the group's account with it. They are not part of SchoolOS's price, and MG Tech charges nothing for them.

Can MG Tech see or use our keys?

They are stored encrypted, only their last four characters show, and nothing is sent from an MG Tech account.

Which three links does Meta ask for, and who writes their pages?

When you set up your app, Meta asks for a privacy policy URL, a terms of service URL and a data deletion callback URL. All three are pages on your public site, in the group's name: the privacy notice, the WhatsApp and SMS messaging terms, and the data deletion page. SchoolOS writes them from what it holds about you, in your site's language; you write nothing. They open even before the site is published, so Meta can read them when it reviews your app.

What happens when someone asks for their data to be deleted on the data deletion page?

A “Destroy their data” request is recorded under “Data subject requests”, due in 30 days; whoever manages the settings is told in their bell, and the privacy email gets a mail if one is saved. Verify who sent it before carrying it out: the request is filed under what they typed, not matched to a record you already hold.

What happens when someone asks Meta to delete their data from your app?

Meta calls the data deletion link you pasted under “Data deletion callback URL”, with a request signed with your app's secret. The same “Destroy their data” request is recorded under “Data subject requests”, about “Meta user” and their id in your app, from “Meta: the data deletion callback”, with no name and no mobile number; the bell and the mail go as for a request from the page. Meta gets a confirmation code and the link to a page where the person sees their request's state and its date, nothing more, and the state follows your answer to the request. If Meta sends the same request again before you answer, it gets the same code and no second request is recorded. A request without your app secret's signature is refused, so save the app secret on the WhatsApp card.