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.

Telegram

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

1. In Telegram, open a chat with @BotFather.
2. 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.
3. BotFather replies with a token (looks like 1234567:AA…). Copy it.
4. 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.

1. 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.
2. In the console, Channels → Connect a channel → Slack, choose the bot to assign, and paste the bot token and signing secret.
3. 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.
4. Reinstall the app so the new scopes and subscriptions take effect.

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.

1. 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.
2. 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.
3. 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.
4. 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.

1. In the console, open Channels → Connect a channel and pick Messenger, Instagram or WhatsApp.
2. Choose the agent that should answer messages on this channel.
3. Click Continue with Facebook and authorize in the popup, selecting the Page, Instagram account or WhatsApp number you want to connect.
4. If your authorization covered more than one Page or Instagram account, Hania asks which one this channel should use. Otherwise it connects straight away.

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.

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

1. 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.
2. 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:

1. 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.
2. Extend the token in the Access Token Debugger with Extend Access Token.
3. Call GET /me/accounts for the Page's id and its token. A Page token taken from a long-lived user token doesn't expire.

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

1. 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.
2. 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.
3. 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.

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.

Connecting a channel

1. Open Channels in the console and choose Connect a channel.
2. 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).
3. Choose the agent that should answer messages on this channel. (Create an agent first if you have none.)
4. 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.
5. Connect. A bot can have more than one channel, and you can connect the same platform for several bots.

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.
• Facebook didn't return the ids for this account - you authorized, but not for an asset this channel needs (a Page for Messenger, a linked Instagram account, a WhatsApp number). Run Continue with Facebook again and select the right asset, or use Connect with your own Meta app instead.
• 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.

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.