Deploy

Messaging channels

Connect Facebook Messenger, Instagram, WhatsApp, Telegram, Slack, or Email to a bot so people can reach it where they already are. This is the connect counterpart to voice numbers: a number is purchased, a messaging channel is connected with your own credentials. Manage them in the console under Channels.

Supported platforms

The three Meta platforms connect either with a single click through Facebook or through your own Meta app, whichever suits you. The rest are connected by pasting a token or an address. Anything secret is stored encrypted and never shown again.

Platform	What you provide	Credential
Messenger	nothing, or your own Meta app	None when you authorize with Facebook. Own app: `page_id`, a long-lived Page access token, and your app secret
Instagram	nothing, or your own Meta app	None when you authorize with Facebook. Own app: `page_id`, `ig_account_id`, the linked Page's long-lived token, and your app secret
WhatsApp	nothing, or your own Meta app	None when you authorize with Facebook. Own app: `phone_number_id`, `waba_id`, a System User token, and your app secret
Telegram	nothing extra	Bot token from @BotFather
Slack	the app's signing secret	Bot User OAuth token (`xoxb-…`)
Email	the inbox address	None. Hania gives you a webhook URL; your email provider generates a signing secret you paste back

Telegram is the simplest channel to connect: free, instant, no app review or fees.

In Telegram, open a chat with @BotFather.
Send /newbot and follow the prompts to pick a name (the display name, e.g. "Acme Support") and a username. The username has to end in bot and be 5 to 32 characters, letters, numbers and underscores only, e.g. acme_support_bot.
BotFather replies with a token (looks like 1234567:AA…). Copy it.
In the console, Channels → Connect a channel → Telegram, choose the bot to assign, and paste the token. That's it; no ids to enter.

Hania validates the token and registers the webhook for you, so you can message the bot on Telegram straight away. Back in BotFather, /setdescription, /setuserpic and /setcommands polish how the bot looks to people.

Slack

Slack connects a Slack app to a bot, so the bot answers direct messages and @-mentions in your workspace.

Create a Slack app in your workspace. Under OAuth & Permissions, add the bot scopes im:history, app_mentions:read, and chat:write, then install the app to get its Bot User OAuth token (xoxb-…). Copy the Signing Secret from Basic Information → App Credentials.
In the console, Channels → Connect a channel → Slack, choose the bot to assign, and paste the bot token and signing secret.
Hania returns a Request URL. In your Slack app under Event Subscriptions, enable events, paste it as the Request URL, and subscribe to message.im and app_mention.
Reinstall the app so the new scopes and subscriptions take effect.

Want a whole team of agents in a Slack channel? That needs a few more settings in the same Slack app, including the /team command. See Bring the team into Slack.

Email

Email is passive; there's no token to paste. You give Hania an inbox address, wire your email provider to forward mail there, and the bot reads each message and replies through its own email tool (your SMTP/ESP; Hania isn't the sender). Setup is two steps, and the inbox stays Pending until you finish the second.

In the console, Channels → Connect a channel → Email, choose the bot to assign, and enter the inbox address (e.g. [email protected]). Hania shows a webhook URL; copy it.
In your email provider, set up inbound forwarding for that address to the webhook URL. The provider generates a signing secret for that webhook. Any provider that supports signed inbound webhooks works; BlacklistGuard is one example.
Back in Hania, paste that signing secret into the inbox's Signing secret field (on the setup screen, or later via the inbox's Edit view). This arms the inbox: it flips from Pending to Active. The secret is write-only; Hania shows only whether one is configured, and the same field rotates it.
Make sure the assigned bot has an email-sending tool and is configured for email replies (not, say, a voice receptionist). Without a sending tool it can read incoming mail but can't respond; the setup screen warns you when that's the case.

The Meta platforms

Messenger, Instagram and WhatsApp each offer two ways to connect, and you can use either:

Quick connect with Facebook, below. You authorize in a Facebook popup and Hania sets the channel up from what Facebook hands back. Nothing to generate, copy or maintain.
Your own Meta app. You create an app, generate a long-lived token, and paste it in along with your app secret. More setup, but the app, the token and the webhook are yours. It also needs no App Review.

Quick connect is the simpler of the two and the one to reach for first. Instagram works the same way as the other two, with one prerequisite: the account has to be a professional account (Business or Creator) linked to a Facebook Page you manage, because Instagram DMs arrive on the account and replies go out through that Page. You grant that Page in the popup, and Hania works out the Instagram account from it.

Instagram: turn on Connected Tools before you connect. In the Instagram app, open Settings → Messages and story replies → Message controls → Connected tools and switch on Allow access to messages. With it off, Meta hands over no DMs at all, and there's no error anywhere to tell you so. It's a setting on the Instagram account rather than on any app, so it applies whichever way you connect.

In the console, open Channels → Connect a channel and pick Messenger, Instagram or WhatsApp.
Choose the agent that should answer messages on this channel.
Click Continue with Facebook and authorize in the popup, selecting the Page, Instagram account or WhatsApp number you want to connect.
The channel connects as soon as the popup closes. There is nothing further to fill in.

For Messenger and Instagram, grant exactly one Page. Facebook tells us which Pages you granted but not which one you meant, so granting several is refused with a message listing them, and granting all of them is refused too (Facebook then names none). Either way you run Connect again and pick the single Page. Granting one connects it straight away. On Instagram, Facebook only offers Pages that have a professional account attached, so there is usually only one to choose.

Instagram messaging rides on the Facebook Page your professional account is linked to, so link them first if you haven't; that Page is the one you grant. WhatsApp runs on Meta's Cloud API and connects the number in your WhatsApp Business Account. Messenger and WhatsApp channels can also take inbound voice calls for voice-enabled bots, which needs extra per-account setup on Meta's side and a bot configured for voice.

Quick connect is the path to use. You can connect a Page, an Instagram account or a business number in a few clicks without creating a Meta app, generating a token, or going through App Review yourself: you authorize in Facebook's window and the channel is live, with nothing to maintain afterwards. Connecting with your own Meta app stays available as the alternative, and is still the right choice if you'd rather own the app and the token.

If Continue with Facebook doesn't complete for you, whether that's a popup blocker, a business account with unusual permissions, or an asset Facebook won't return the ids for, connect with your own Meta app instead. That path doesn't use the popup at all.

Connecting with your own Meta app

On the connect form, choose Connect with your own Meta app instead and enter the ids, a long-lived token, and your app's App secret (from Settings → Basic in your app dashboard). Hania then gives you a callback URL and a verify token to enter in your app's webhook settings, which is what makes messages flow.

Connect with your own Meta app is the full walkthrough: creating the app, making it Live, the webhook fields to subscribe per product, and why no App Review is involved. The sections below cover just the fiddly part, getting the ids and a long-lived token out of Meta.

On this path the token must be the right type and long-lived: a Page token for Messenger and Instagram, a System User token for WhatsApp. A channel receives messages around the clock, so a short-lived token stops working within hours and breaks the channel. Meta's Access Token Debugger tells you both: Type for the kind, Expires for the lifetime. (Telegram bot tokens don't expire, and the Continue-with-Facebook path has no token to expire at all.)

WhatsApp needs a Phone number ID, a WABA ID and a System User token:

In Meta for Developers, open your app's WhatsApp use case page. The try it out panel at the top carries both the WhatsApp Business Account ID (the waba_id) and the Phone number ID, a long number rather than the phone number itself. Copy both.
Generate a System User token rather than the temporary one that panel offers. In Business Settings → System users, add a system user with the Admin role, use Add Assets to assign your app, then Generate new token granting whatsapp_business_messaging, whatsapp_business_management and business_management, with the expiry set to Never. Copy it; it's shown once.

The temporary token beside those ids lasts about a day, so a channel connected with it runs until then and quietly stops. Connect with your own Meta app has the rest of the WhatsApp path: the test number's recipient list, moving to a real business number, and the webhook field you have to subscribe by hand.

Messenger needs a Page ID and a Page token that doesn't expire, both from the Graph API Explorer with your app selected:

Generate a User token granting pages_show_list, pages_messaging, pages_manage_metadata and pages_read_engagement. In the consent popup, tick the Page you're connecting; the popup keeps your last selection, so a new Page has to be ticked explicitly.
Extend the token in the Access Token Debugger with Extend Access Token. What you get back is a long-lived User token, which the Page token in the next step inherits its lifetime from.
Call GET /{page-id}?fields=access_token for the Page you're connecting. The access_token it returns is the Page token, and it's the one the connect form wants. Your Page ID is in Meta Business Suite under the Page's settings, and it's the same number you enter on the form.

Don't stop at step 2. The extended token looks like the finished article, but pasting a User token into the form gets you (#210) A page access token is required to request this resource from Meta. Only the Page token works.

Don't use GET /me/accounts to find the token, whatever else you may have read. It leaves out any Page on Meta's New Pages Experience, which is now the default, so for most accounts it just returns an empty list and gives no hint as to why.

Before you connect a Messenger channel, turn off the Page's automations in Meta Business Suite, under the Page's Inbox. Instant Reply, Away Message and FAQ autoresponders are all answered by Meta's own Page Inbox, and when that happens Meta never fires the messages webhook. The channel connects, the webhook verifies, and your agent still never sees a thing. More on this.

Instagram needs both ids and the linked Page's token:

Link your Instagram professional account (Business or Creator) to a Facebook Page, and in the Instagram app switch on Settings → Messages and story replies → Message controls → Connected tools → Allow access to messages. With that off, nothing reaches the channel.
Get the Page ID and a long-lived Page token exactly as for Messenger, granting instagram_basic and instagram_manage_messages as well, and ticking the Instagram account in the consent popup.
Call GET /{page-id}?fields=instagram_business_account for the Instagram account ID. Read it from there rather than guessing: a wrong id connects without complaint and then routes nothing.

Instagram messaging runs on the Messenger use case, and its webhook settings live in that use case's Instagram settings section. The dashboard also has a standalone Instagram use case with a form that looks the same; it belongs to a different integration signed with a different secret, so configuring a channel there fails signature checks permanently while its Test button keeps passing.

Inbound Instagram messages arrive on the Instagram account while replies go out through the linked Page. Hania handles that routing either way; on this path you just supply both ids.

An own-app Instagram channel only receives DMs from people who have a role on your Meta app until the app passes App Review. It's enough for a pilot, and a public inbox needs the review first. Who can message you explains the options. Messenger and WhatsApp have no equivalent limit.

Connecting a channel

Open Channels in the console and choose Connect a channel.
Pick the platform; the form then asks for what that platform needs (ids for the Meta platforms; just the token for Telegram; a token + signing secret for Slack; just the address for Email).
Choose the agent that should answer messages on this channel. (Create an agent first if you have none.)
Enter the platform ids and paste the token. You can add a display name, but you don't need to: leave it blank and the channel is labelled with the account's own name (the Messenger Page name, the Instagram @username, or the WhatsApp verified name and phone). Set it only to override that with your own label.
Connect. A bot can have more than one channel, and you can connect the same platform for several bots.

Connecting a channel no longer asks for a tenant or workspace id; the workspace is taken from the bot you assign.

Validation on connect

When you connect, Hania subscribes the account's webhooks before saving, which also validates the token, ids, and permissions. If any of those are wrong, the connect fails and the underlying platform (Graph API) error message is shown so you can fix it. Connecting an account that's already connected is rejected too.

Troubleshooting

The Facebook popup doesn't open, or closes immediately - a browser popup blocker or a content blocker is usually the cause. Allow popups for the console and connect.facebook.net, then try again. If it still won't complete, connect with your own Meta app, which doesn't use the popup.
"You granted N Pages…" - the authorization covered more than one Page, so Facebook can't tell us which one you meant. The message lists them. Run Continue with Facebook again and tick only the Page you want on Facebook's asset-selection screen.
"Could not determine which Facebook Page to connect" - usually the opposite of what it sounds like: you granted access to all your Pages rather than one, and Facebook then names none of them, so there's nothing to single out. Run Continue with Facebook again and grant one specific Page, or use your own Meta app to paste a Page access token directly.
"Could not determine which Instagram account to connect" - the Page you granted has no Instagram professional account linked to it, or the account linked to it is a personal one. Switch the account to Business or Creator in the Instagram app under Settings → Account type and tools, link it to the Page, then run Continue with Facebook again and grant that Page. Pasting a Page access token through your own Meta app is the other way round it.
An Instagram channel connects but no DMs ever arrive - Allow access to messages is off on the Instagram account, under Settings → Messages and story replies → Message controls → Connected tools. Meta keeps the messages rather than passing them on, so neither side has anything to show for it. Switch it on and the channel starts working; there's no need to reconnect.
Quick connect fails on a permission you're sure you granted - Facebook won't re-ask for permissions it thinks the app already has, so an authorization you gave earlier keeps running without any added since. Run Continue with Facebook again and watch for the permission screen. If Facebook goes straight past it, remove Hania under Settings & privacy → Settings → Business integrations on your Facebook account and connect once more, which forces a fresh consent.
Facebook didn't return the ids for this account - a WhatsApp authorization that didn't cover a number. Run Continue with Facebook again and select the right number, or use Connect with your own Meta app instead.
Quick connect can't get an access token for the Page - not every Page can be connected this way yet, and there is nothing to correct on your side when it happens. Connect that Page with your own Meta app instead, pasting its Page access token directly. Other Pages are unaffected.
Connect fails with "(#210) A page access token is required" - a User token was pasted where Messenger and Instagram need a Page token. It's what Extend Access Token gives you, so it's an easy one to stop at. Call GET /{page-id}?fields=access_token and use what that returns. See generating the token.
GET /me/accounts comes back empty - the Page is on Meta's New Pages Experience, which that call doesn't list, and it's the default now. Nothing is wrong with your token. Ask for the Page directly with GET /{page-id}?fields=access_token.
A Messenger channel connects but the agent never answers - the Page has automations switched on, so Meta's Page Inbox is answering instead and the messages webhook never fires. Turn off Instant Reply, Away Message and any FAQ autoresponders in Meta Business Suite. A canned reply arriving a few seconds after the customer writes in is the giveaway. See turning off the Page's automations.
A Meta channel connected with a token works for a while, then goes quiet - the token was a temporary one. WhatsApp's lasts about a day; a short-lived Page token goes sooner. Generate a System User token for WhatsApp, or a long-lived Page token otherwise, and reconnect the channel. Connecting with Facebook avoids this entirely.
An own-app Meta channel verifies but never delivers - saving the callback URL and subscribing the webhook field are two separate actions in Meta, and the field's Test button works either way, so a successful test proves nothing. Check that messages is subscribed. See the webhook step.
An own-app Instagram channel replies to you and nobody else - Meta only delivers DMs from people with a role on an app that hasn't passed App Review. See Who can message you.
Every message is answered twice - a second app is still subscribed to the Page on Meta's side, usually because the account was connected through Hania's own app before and removing that channel didn't clear the subscription. Get in touch and we'll sort it out as you switch.
An own-app Instagram channel reports signature failures - the webhook was configured in the standalone Instagram use case, which is a different integration with a different signing secret. Instagram webhooks for this integration belong in the Messenger use case's Instagram settings. See the webhook step.
Saving the webhook in your own Meta app fails with a 403 - the callback URL has to belong to a connected channel before Meta can verify it. Connect in Hania first, then save the webhook; if you're re-saving after removing a channel, point the app at one that's still connected. See the webhook step.
You need the callback URL or verify token again - both are in the channel's Edit view, and both stay the same for as long as the account is connected.
Slack shows "Request URL failed" - the app hasn't been installed to the workspace yet, or the signing secret doesn't belong to the same app the bot token came from.
Slack connects but the bot never answers - the two bot events (message.im and app_mention) weren't subscribed, or the app wasn't reinstalled after adding them.
Inbound email is rejected - the inbox hasn't been armed. Paste your provider's signing secret to flip it from Pending to Active.
Email arrives but the bot never replies - the assigned bot has no email-sending tool, so it can read mail but not respond.
Connect fails outright - the platform's own error message is shown. It's usually a wrong id, a permission missing from the token, or an account that's already connected.

Editing, reassigning & removing

Use Edit on a channel to rename its label or reassign it to a different bot, with no reconnect needed. The platform, its ids, the token and the app secret are fixed; to change any of those, remove the channel and connect it again (you'll paste the credentials once more, since they're never stored in a readable form). Reconnecting an own-app channel keeps the same callback URL and verify token, so your Meta app's webhook settings are still correct and need no change. Removing a channel stops it from receiving messages immediately.

Messenger, Instagram and WhatsApp can each be connected either with one-click Continue with Facebook or through your own Meta app. Still to come: outbound calling on channels, and per-channel billing.

Every message that arrives on a connected channel becomes a conversation tagged with that platform's channel, so you can review and report on it alongside your other channels.

Two ways to reach a bot aren't connected here, because they don't use anyone else's credentials: the website widget, which you set up entirely in Hania and paste into your site as a script tag, and SMS or phone calls, which use a phone number you get through Hania rather than a channel you connect.