Connecting Facebook, Instagram and WhatsApp

To receive your customers' messages in TSync, you connect your own Meta app. They don't go through our servers: the conversations travel directly between Meta and your installation.

The guide is written for someone who has never been inside the Meta console. It takes 20–30 minutes for Messenger and Instagram, plus another 20 for WhatsApp.

The most useful tip in the whole guide: for the main pages, don't hunt through the menus — the Meta console changes its structure often, and the same things show up under similar names in different places. Use the direct links below.

With one exception: inside a use case (the Customize screens) direct links do not work — Meta moves you to a different use case without telling you. Those are reached through the menu only. Explained where it matters, further down.

Before anything else: the two Meta consoles

You'll be working in two different places, and mixing them up is the number one reason people get stuck.

At every step below we tell you which console you're in.

You'll need the app ID (APP_ID) and the business ID (BUSINESS_ID). You can see them in the page address while you're in the console, and you use them in the links below.

Step zero — if you don't have a Meta app yet

Skip this section if your app already exists. If it doesn't, the rest of the guide has nowhere to start: every key below comes out of an app on your own account.

Why it's yours and not ours. We could have made a single TSync app shared by every customer — you'd connect in 60 seconds. We deliberately chose otherwise: your messages would then travel through our infrastructure, which would make us a processor of your data. This way conversations go straight from Meta to your installation and we never see them. The cost is the quarter of an hour below, once.

Meta explicitly allows this without special review, as long as the app serves your own Page. Meta's review is for anyone wanting access to other people's Pages — that isn't you.

You need: a personal Facebook account that administers the Page (it cannot be done from the Page account), an admin role on the company Page, optionally the professional Instagram account linked to the Page, and your TSync address with valid HTTPS.

The tip that saves hours: do the whole thing in an incognito window, with no browser extensions. The Meta console freezes on extensions constantly — panels that never load, buttons that don't respond — and the error it shows never says so.

1. Create the app

developers.facebook.com → My Apps → Create App. Give it a recognisable name (e.g. "Acme ERP Connector"), and use a contact address you actually read — that's where Meta sends its warnings.

2. Fill in the basics

App settings → Basic:

If the icon upload returns "Something went wrong", it is almost certainly a browser extension rather than the icon. Try again from incognito.

3. Add the use cases

Use cases → Add use cases. You need three:

• Engage with customers on Messenger — Facebook messages;
• Manage messaging & content on Instagram — Instagram messages and comments;
• Manage everything on your Page — comments on the Facebook Page.

Don't add others "just in case". Every use case widens the permission surface, and if you ever do go to Meta review, each permission has to be justified separately. The less you ask for, the simpler it gets.

4. Turn on the permissions

For each use case: Customize → Permissions and features, then Add on each one below.

The difference between the two read permissions is worth remembering: pages_read_engagement gives you what your Page posted; pages_read_user_content gives you visitors' comments. Meta treats them as different things, and missing the second is the usual reason "comments don't show up".

A verified trap: the Add button sometimes returns "Something went wrong" even though the permission was actually added. Don't keep pressing — reload the page and look at the state. If it says "Ready for testing", you're fine.

5. Get the Page token and app_secret

Tools → Graph API Explorer, select your app, tick the permissions above, Generate Access Token, and go through the Facebook dialog. Then run me/accounts?fields=id,name,access_token — that gives you page_id and page_access_token.

The token must be long-lived. The one you get straight out of the Explorer expires in 1–2 hours, and your connection would die silently the next day. A Page token derived from a long-lived user token never expires.

app_secret comes from App settings → Basic, pressing Show (it asks for your Facebook password).

With those four — page_id, page_access_token, app_secret and a verify_token you invent — move on to the next part.

6. When you subscribe the webhook, don't forget messaging_referrals

When subscribing fields (below, at the webhook step) you'll see messages, messaging_postbacks, messaging_referrals and feed. messaging_referrals is the one that carries ad attribution — without it you won't know which ad a conversation came from, and that cannot be recovered afterwards.

Part 1 — Messenger and Instagram

What you give TSync

Go to Omnichannel → Accounts, press "+ New account" and pick the Messenger / Instagram Direct channel. You have four fields to fill in:

⚠️ For a new account always press "+ New account", never "Edit". The create form and the edit form are the same form. If you change the channel while you're on "Edit", saving turns the existing account into the new one instead of creating a new account.

Once you save the account, TSync shows you the webhook URL. That's the one you paste into Meta, together with the verify_token you chose.

app_secret — and why nobody else should be asking you for it

developers.facebook.com/apps/APP_ID/settings/basic/

Press Show next to App Secret. Meta asks for your account password.

Nobody — not us, not a consultant — should ask you for your password. You reveal the value yourself and paste it straight into TSync.

Worth knowing: TSync doesn't show secrets back to you. When you reopen an account to edit it, the secret fields are empty. Nothing has been lost — they're saved, they just aren't displayed, so they can't be read off the screen.

The step everybody misses

Meta has two levels of event subscription, and the console only shows you one:

• you tick a field in the app console → you've subscribed the app;
• the Page keeps a separate list and does not pick up a field added after it was connected.

When the two don't match, the field looks switched on and simply nothing arrives — with no error, anywhere. It's a silence, not a failure, which is why it's so hard to find.

You don't have to deal with this yourself. Open Omnichannel → Health. There TSync asks Meta directly which fields your Page receives and shows you the list. If any of them says "not delivering", the "Subscribe the Page to the missing fields" button appears — press it and you're done.

The button also keeps the subscriptions you already had (for example feed), it doesn't replace them.

Part 2 — WhatsApp

The decision you make first, not last

A number in use in the WhatsApp app cannot be connected through the API while it's there.

To move it, you have to delete the WhatsApp account on that number — and then:

• the conversation history is lost;
• the number can't come back to the app unless you take it out of the API.

You have two options:

We recommend option B. A dedicated number doesn't create confusion with someone replying from a phone, and the decision stays reversible.

WhatsApp Web doesn't help. web.whatsapp.com is just a mirror of your phone — the same app, a different screen. It has no API and can't be connected. Likewise, business.whatsapp.com isn't a console, it's a marketing page.

Try it first with the test number — free, and you delete nothing

Meta gives you a test number that can write to at most 5 numbers you declare. With it you check that everything works without touching your real number.

Do this before the decision above. That way you choose at the end, with things already proven.

developers.facebook.com/apps/APP_ID/use_cases/ → Connect with customers through WhatsApp → Customize → Step 1. Try it out

1. It picks your business portfolio for you. Press Continue.

   ⚠️ This button accepts Meta's terms for WhatsApp Business — a commitment by your company, not just a setting. Read it first.

2. Press Claim test number. Your WhatsApp account and the number are created.

⚠️ If the right-hand area stays blank, don't reload — that isn't the problem.

Links that point straight inside a use case (…/use_cases/customize/…) do not hold: Meta bounces you back to the default use case, usually Messenger, and the WhatsApp panel simply never appears. It is not a slow load, and waiting does not help.

What works: go back to developers.facebook.com/apps/APP_ID/use_cases/ and press Customize on the Connect with customers through WhatsApp row itself. From there the left-hand menu takes you anywhere correctly.

The same rule applies to Permissions and features, Step 1 and the rest: reach them through the panel's own menu, never through a direct address.

"No phone numbers available for this app" — not what it looks like

That sentence sits under Step 1 and reads as the account has no number. It almost never means that. It answers a different question: what the app can see. The number can be sitting in WhatsApp Manager, visible in another tab, while the app cannot see it at all — because the app is not linked to the WhatsApp account.

There are two links, and the console shows one:

Without the second, nothing arrives and Meta reports no error. You press Claim test number and nothing happens, as many times as you like.

TSync handles it. Fill in the WhatsApp Business Account ID on the account (Omnichannel → Accounts → Edit), then open Omnichannel → Health. It shows:

• whether the app is subscribed to the account — and a button that subscribes it;
• which numbers the app can actually see, with the phone_number_id (no more copying it by hand out of a console screen).

An empty list under a working query means the link is missing. A query that errors means something else — permissions. Health keeps the two apart, because they are fixed differently.

The WhatsApp Business Account ID is in WhatsApp Manager, in the page address as asset_id=…, or under Business Settings → WhatsApp accounts, beneath the account name.

Three different things that sound alike

WhatsApp needs three separate things before the first message leaves. The console shows none of them, and when one is missing the error messages resemble each other enough to send you the wrong way. TSync keeps them apart, in Omnichannel → Health:

The six-digit PIN is not a formality. It becomes the number's two-step verification PIN, and WhatsApp asks for the same one at every later re-registration. TSync keeps it with the account so it cannot be lost.

"Send a test" — the shortest route to the right answer

The same panel has a number field and a Send a test button. It sends a real message and shows you exactly what Meta answered, in Meta's words and with the error code — not a rewording of ours.

Leave the text empty and it sends the hello_world template, pre-approved on every account and valid outside the 24-hour window. A failure then says something about the account, not about the conversation.

Use it before hunting through menus: the console describes states, the test produces facts.

The Health page remembers Meta's answers for two minutes, and says how old they are. That is on purpose: the page you open because something is wrong with Meta is the page most likely to be slow when something is wrong with Meta, and asking four questions with a long patience each adds up to more than your web server allows — you would get the server's error page instead of ours. After you change something at Meta's end, press Read again now rather than trusting a reading that is up to two minutes old. Actions you press yourself — registering a number, creating a template — keep their longer patience: those are a person waiting for a result, not a page drawing itself.

Templates: how you write first

On a real number you can reply freely for 24 hours after the customer messaged you. To write first, you need a template approved by Meta.

Omnichannel → WhatsApp templates shows everything you have, with its real state: APPROVED (can be sent), PENDING (under review, usually minutes) or REJECTED — in which case Meta's reason is shown too, the one sentence that says what to change.

You create a new one from the same page, in Romanian, Russian and English in a single press. Worth knowing:

• The name is shared by all three languages: lowercase letters, digits and underscores.
• The category matters. UTILITY means "about an existing request or order". Meta re-classifies what you submit and refuses a mismatch — a body containing "no. {{2}}" was read as a verification code and rejected before it was ever sent.
• Variables are written {{1}}, {{2}} and may not open or close the message.
• Sample values are required, one per variable. Meta reviews the rendered message, not the skeleton. Invent them: they travel to Meta, so never a real customer's data.
• A language left empty is simply not created, and each language gets its own verdict.

Once one is approved, press Import the approved ones. That copies it into TSync's own library so it can be sent from a conversation or a campaign without anybody retyping the name — the name has to match Meta's exactly, and a single typo answers "no template" at send time and explains nothing further. Only approved ones are imported, and re-running refreshes rather than duplicates.

The test number has a recipient list

A test number can only send to numbers added in advance (five at most), from the app's Step 1 panel. If that panel will not show you your number — it happens — the test number is only good for receiving. To send to anyone, move on to Step 2. Production setup with a real number.

A real number cannot be used in the WhatsApp app at the same time. See the decision above about choosing the number: it is irreversible and worth making once, correctly.

Where to find phone_number_id

It's not the phone number. It's a code of about 16 digits, and if you mix them up the error doesn't tell you what the problem is.

business.facebook.com/latest/whatsapp_manager/phone_numbers/?business_id=BUSINESS_ID

Press the ⚙ gear on the number's row. The panel that opens says, in those words, "Phone number ID: …". That's the value.

The token: pick the one that doesn't expire

With the temporary token, the integration works today and looks broken tomorrow. The few extra minutes are worth it.

business.facebook.com/latest/settings/system_users/?business_id=BUSINESS_ID

1. Add → a name of your choosing (for example tsync-omnichannel), role Employee (Admin isn't needed).

   The first time you add one, Meta asks you to accept a policy on behalf of system users. That too is a commitment by your company.

2. Assign assets — to be done twice, otherwise the next step gets stuck:

   • WhatsApp accounts → your account → the Messages permission;
   • Apps → your app → Develop app.

3. Generate token → pick the app → expiry Never → the WhatsApp permissions.

If you ever want to withdraw access, the Revoke tokens button is on the same system user.

What you give TSync

Omnichannel → Accounts → "+ New account", the WhatsApp channel: phone_number_id, the WhatsApp Business Account ID, the token, app_secret and the verify_token you chose.

The account ID is not decoration: without it TSync can neither check nor repair the link described above.

The last step — publish the app, or nothing arrives

The Meta app is created in Development mode. In that mode delivery is limited and unreliable: Meta allows it only to people with a role on the app (admin, developer or tester), and even that tester access is time-limited and lapses — a message that arrived last week may simply stop arriving, with nothing changed on your side. And Meta's console now states, on the Page's webhook screen: "No production data, including from app admins, developers or testers, will be delivered unless the app has been published." Whatever the exact rule at any given moment, the practical conclusion is one: until you publish the app, Messenger and Instagram do not deliver reliably — often they do not deliver at all.

The effect is exactly the silence this whole guide keeps warning about: you configure everything correctly, send a test message — and nothing appears in the inbox, with no error anywhere. Nothing is broken; the app is simply unpublished.

Publishing:

1. developers.facebook.com/apps/APP_ID/ → in the left menu, Publish (it carries the Unpublished badge).
2. If it reads "All required app settings are complete", press the Publish button (bottom-right).
3. Meta confirms "Your app was successfully published" and the badge turns to Published.

The switch is reversible — the same place then offers an Unpublish button.

You need neither App Review nor to become a "Tech Provider" as long as the app serves your own Page. Those are required only if a single app were to serve OTHER businesses' pages — which is not your case, and is exactly why each business builds its own app.

WhatsApp is the exception: it delivers even in Development mode, so if you use only WhatsApp this step does not block you. But for Messenger and Instagram publishing is mandatory — it's the last thing to do before testing.

How you know it worked

1. Omnichannel → Health — every field says "delivering", and there's no warning at the top.
2. Send yourself a message from your phone to the Page. It should show up in the Omnichannel Inbox within a few seconds.
3. Reply from TSync. The message should arrive on the phone.
4. Reply from the phone to the message you sent. The thread should show which message you replied to.

If step 4 shows "As a reply to an earlier message" instead of the text of the message, open Health: it almost certainly means the Page is missing a field, and the button there fixes it.

What's on you, and what nobody can do for you

• The Meta account password — required to display app_secret. Don't give it to anyone.
• Accepting Meta's terms for WhatsApp Business and the policies for system users — these are commitments by your company.
• Deleting the WhatsApp account on a number, if you go with option A — it's irreversible and it loses the history.

The rest can be done by your TSync administrator.