In this post, with the use of API tooling, you’ll learn how to initiate a business conversation by sending a WhatsApp Message Template, how to receive a message sent to the WhatsApp business account and how to respond to the user-initiated conversation by sending a free-form text message.
Building an Application with the tyntec API for WhatsApp
By testing this complex workflow manually on your local computer you make sure your WhatsApp Business Account and the Message Templates are set up correctly and you understand the design of the tyntec API for Whatsapp. The local tooling for the manual workflow is a convenient placeholder to be replaced later with your programmatic implementation.
For the local development and debugging of the tyntec API you’ll need three components:
Requirements from the previous post:
- tyntec account and API key
- WhatsApp Business Account (aka WABA) with a verified phone number.
- tyntec authorized in your Facebook Business Manager account
- WhatsApp Message Templates submitted and approved for initiating a conversation (aka the Templates)
Before we get started, a few words about the webhook URI:
The tyntec API is using webhooks for delivery of incoming messages to your WABA. We need to expose an HTTP endpoint by implementing `POST’ HTTP method to set up the webhook URL with tyntec. This endpoint of your application will be responsible for processing the incoming messages.
Even though it’s a POST method, It’s a good practice to have the webhook deeper in the URI namespace so that it doesn’t occupy the root URI (`/`). So, let’s make the webhook URI `/callback/message`.
The webhook’s entire webhook URL will be http://<yourserver>/callback/message. Let’s focus on the `<yourserver>` part now so that we can set up the entire URL with tyntec and start receiving messages.
For the reception of the incoming API webhooks we need the web server to be accessible from the internet. Most developers don’t have that on their local computer, so we’re going to use Ngrok to tunnel localhost ports from our computer and expose them on the internet.
The paid version of Ngrok.io gives you a persistent, public URL tunneled to your localhost. You can provide this URL to tyntec as the temporary webhook target for the local development and debugging of the tyntec API webhook callbacks.
Trust me, ngrok.io is worth the few dollars. It will save you a lot of headaches. The paid version gives you persistent URLs and end-to-end encryption needed to introspect the incoming webhooks from the tyntec API.
Now, let's get `ngrok` ready on your local computer:
- Sign up for a ngrok.io account
- Get yourself the Pro Plan with monthly billing so that you can terminate the contract after completion. You would need a credit card.
- Download and install `ngrok` CLI binary or the NPM wrapper package
- `npm install -g ngrok`
- Authorize the CLI with the Pro account
- `ngrok authtoken <YOUR_AUTH_TOKEN>` (see the Ngrok Dashboard > Connect your account)
The free-of-charge alternatives for the tunnel component not covered by this tutorial are:
- Often too slow or even entirely down localtunnel.me
- `ssh -R` to your own *nix server accessible from the internet which is often too slow or down serveo.net (also supported by ngrok.io in paid version)
- requestbin.org to introspect the requests from tyntec, but it doesn't act as a proxy
SETTING UP A DEBUGGABLE `ngrok` WEBHOOK ENDPOINT
Ngrok is hosting the public entrypoints to the tunnels on their domain, we want to stay with the data within the EU and we’ve picked `shoeshop’ as the name of the tunnel. Our tunnel root URL is `http://shoeshop.eu.ngrok.io` and that means the webhook URL will be: `https://shoeshop.eu.ngrok.io/callback/message`.
Pick your tunnel name and create the tunnel with the `ngrok` command, exposing publicly the localhost port 3000, with substituted <TUNNEL_NAME>. You should get the tunnel root URL. Your tunneled and debuggable webhook URL is this root URL + the webhook URI you’ve decided for in the previous step. In our example the webhook URL is https://shoeshop.eu.ngrok.eu/callback/message
Send the webhook URL to firstname.lastname@example.org.
`$ ngrok http -region eu -subdomain <TUNNEL_NAME> 3000`
With that, the tunnel should be set and running (but not listening yet), forwarding all the HTTP and HTTPS requests to the public webhook URL to http://localhost:3000 Note that the tunnel will be running only up until you terminate the `ngrok` process.