I Hate Twilio
Do you hate Twilio as well? Have you ever tried setting up a WhatsApp integration before and realized just how confusing Meta is? Well, Twilio certainly did, because that's their business model. Not anymore. Here is a Full Guide to how to entirely self-host the Webhook to WhatsApp Messaging process for less than $10 a month (or even Free, if you have a phone number already). No vendor lockin, no incomplete developer SDK that's missing all the good features, no $250/month support. You get All of the API. Silence, Brand.
(skip the preface if you just want the instructions)
Preface
So, we were happy (sort of) Twilio customers for a bit, until suddenly, my developers started messaging me, saying 'Hey, Whatsapp messages to our production account aren't going through; is it an us issue?' Confused, I disconnected Twilio's webhook from our end, and replaced it with my manual ngrok http URL. Nothing. I checked back on their site; nothing looked wrong, I made sure everything was forwarding to our URL. Still nothing.
Then, I check our company email, and see a "Your account has been suspended for not having enough balance." Strange; why wasn't that front and center on my Twilio dashboard then? It was only when I checked the admin accounts page, that I found it. No worries, I just topped up our account with $100 and moved on. But the massive 'Your account has been suspended' banner on the settings page didn't go away. Instead, it now said something different:
Turns out, they also simultaneously blocked our account for suspicious activity, without telling us. Not only that, there was no "Easy" process to recover our account; (Seven days later, after having figured this out, still nothing by the way). We submitted the standard ticket, made sure to tell them it was urgent, but we couldn't do anything about it. So, I began looking for options. Our Facebook Business account wasn't verified yet at this point, but I was pretty sure that we didn't need it.
This wasn't our first issue with Twilio at this point, so we were just about done. So, I decided to try literally everything to figure out how to get this to work. And boy, there was a lot of failing (I'll give Twilio's support credit; they at least existed. Meta...not so much. If you ever have a problem with Meta...good luck)
How To Twilio For Free
Step 1: Obtain a phone number that isn't blocked by WhatsApp. YBN (below) works great, it's fast, no questions asked. They even have a support WA number (that, mind you, is ACTIVE too!)
Step 2: Create a Facebook Business Account. Preferably, do NOT create one from a newly created email; use a long-standing account that you've used with Facebook or Instagram for a long time, and simply create a business account attached to it.
Step 3: Create a Facebook Developers Account. This has a really funny part; you'll get to a point where you need SMS verification. That won't work; Meta's own endpoint will fail. Instead, you need to go to Meta Pay, click 'Add Credit/Debit Card' (NOT PAYPAL, IT'S NOT ENOUGH), then fill in your details. Once you save, go back to Meta Developers, and reload. It should skip you past to the next section. Once you're done, it should take you to your Developers account home page, with no Apps.
Step 4: Create a new Facebook Developers App; just go to the My Apps section, create a new app, boom. Select the Whatsapp communication Use-Case. Then, you'll want to go to the Use Cases page, click 'Customize' where the use-case is labeled 'Connect with users via WhatsApp' or something, where you can set up the API.
Step 5: Click API Setup. Do NOT create a test number. Don't need it. Instead, click 'Add Phone Number' (it's also Step 5 on their list). Pick the phone number you just got from YBN or elsewhere. Specifically, pick 'Voice Call', and it'll route the Facebook Voice Call to your phone number where you can enter the One Time Pin. Once that's resolved, save, and you should now have a phone number.
Step 6. Payment. At this point, you will probably see a banner up top that says 'You need to add a payment method.' From there, click that; you should eventually get to your Facebook Business account, where you can add a payment method. For reference so we're on the same page, go here. It should automatically have created a new Whatsapp Account for you after doing step 4. There, you'll need to add a payment method to the WHATSAPP ACCOUNT (not just your business account). If you did it correctly, the banner on the Facebook Developers page should vanish after a reload. Don't worry, it's pretty cheap, and already cheaper than the amount Twilio charges on top of that.
Step 7. System User. Meta requries you to have an access token; however, the enticing big button at the top of the Use Cases page for 'Generate Token' only generates a token that expires every 24 hours (You can also go to the Tools > Graph API Explorer page to get a key as well, but that probably expires every 60 days). Instead, go here, or .../latest/settings/system_users?business_id=<BUSINESS_ID>. You shouldn't see any system users yet, so create one.
Step 8. Access Token. Next, click the three dots, and click Assign Assets.
If you're on track, you should see the app that you created. After selecting that, you'll see a choice between 60 day expiry, or Never. You can choose; if you constantly reroll your tokens, probably 60 days; otherwise for simplicity, Never is fine too. Then, you should be on this page:
Select the three permissions here. That will give you enough to handle all of Whatsapp. Once you're done, you should have a token. Copy it down somewhere! You'll never see it again. If you have multiple people on your Facebook Business account, it may say something like 'This action requires someone else on your team to approve.' That's fine, just have them approve it and you're good.
Step 9. Environment Variables. We're now at the point where we have quite a few keys to remember. Here are the main ones:
WA_ACCESS_TOKEN: The token we just got that expires in either 60 days or Never (it should be ultra long).
WA_PHONE_NUMBER: Your number that you got from somewhere.
WA_PHONE_NUMBER_ID: An unique ID tied to the PHONE NUMBER. Used for querying the Whatsapp Business API.
WA_VERIFY_TOKEN: A token that you decide on, used later to verify that your webhook is live.
WA_APP_SECRET: A secret that's used to check that webhook calls are coming from Meta and not a malicious actor. Get it from https://developers.facebook.com/apps/<APP_ID>/settings/basic, or from your app's developer page, bottom left > App Settings > Basic. You'll need to click Show on the button top right to see the secret.
(If you're not sure where the Phone Number ID is, it's this one:)
Step 10. Your API. You'll want to just set up an API. I'm not going to teach you how; if you're using Twilio, you probably have your own opinionated stack. Whatever the case, something like this will probably work, though the documentation may have changed. This by Gareth Wilson at HookDeck is surprisingly well written.
Step 11. Webhooks. Your API needs to be running; if you want to test it, just expose it with ngrok temporarily, then get the link to the webhook. Next, back on the 'Customize Use Case' page of the developers.facebook.com page, find 'Configuration'.
Here, paste in your public webhook URL, and in the Verify token section, put in the WA_VERIFY_TOKEN token we discussed earlier. Your API needs to be available at this point to save; Meta will actually query your API to test that it's available. If it saves, you should then activate the 'Messages' webhook field; that's all you need to receive/reply to messages, but you can certainly do anything you want. Sky's the limit now! No more hiding behind Twilio.
Step 12. Register. Now comes the niche, nitty-gritty part of the guide. I spent SO LONG figuring out this stuff icl, since for some reason it's not easily doable (at least I couldn't find it) via. any web UI. First, we need to register our phone number to the cloud API. With that, we can use curl:
curl -X POST "https://graph.facebook.com/v25.0/<WA_PHONE_NUMBER_ID>/register" \
-H "Authorization: Bearer <WA_ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{"messaging_product":"whatsapp","pin":"<6_DIGIT_PIN>"}'
You can pick this 6 digit pin. Put in the WA_PHONE_NUMBER_ID and the WA_ACCESS_TOKEN we discussed in the right place, and send it in your terminal. It should pause a bit, then reply success true. To check that it worked, you should now be able to set a profile picture on your Whatsapp manager page:
And checking the Two-step Verification page, you should now see this:
Step 13: Subscribe. Right now, the App knows where to forward events to (your webhook URL) but it doesn't know where to get events from. So, we need to make one final link, between the WhatsApp Account and your App:
curl -X POST "https://graph.facebook.com/v25.0/<WABA_ID>/subscribed_apps" \
-H "Authorization: Bearer <WA_ACCESS_TOKEN>"
The WABA_ID is found here:
Finally, we can check that your app is subscribed with one last curl:
curl "https://graph.facebook.com/v25.0/<WABA_ID>/subscribed_apps?access_token=<WA_ACCESS_TOKEN>"
Step 14: Publish. Back on your Developers app page, you should now be ready to publish your app! Before that, though, Meta will want you to fill in some final details, like a Privacy Policy, your Category, yada yada. That's light work compared to what we just went through! Publishing is instant; doesn't require any formal verification at all. And once you're done, you should be able to message to your backend, who can reply!
What's next?
Well, you can go wild! You have full access to the Facebook Developer Documentation; if anything here didn't make sense, check out the Getting Started docs for some less-detailed but pretty much the same information. Ooh, check out flows; that and the Whatsapp Templates thing look really cool! You can do all sorts of nice UI with that, just make sure that you probably need to verify your business with them first. You can also remove any connection to Twilio at this point ;)
And if you made it to the end of this guide and I helped you in some way, I hope you can give this a star and share this with someone else! Any time you spare not using Twilio is time you can get back to building :)
Top comments (0)