A webhook is a handy tool that you can use to transfer information into and out of a web app through simple HTTP requests containing data in a structured format (JSON, in TextIt's case). Better yet, you don't need to have extensive coding experience to make use of them.
In TextIt, we make webhooks available to you through the Call Webhook RuleSet, which sends the phone number of the active contact, their state in the flow, and the flow's name to the URL you specify. See the Flow Event webhook documentation for a full list of the values included in that request. This RuleSet can be used to send information to other service's APIs, like Zapier (see this guide to get started with the TextIt Zapier app), Google Maps, Google Sheets, and really any other service that provides a JSON API. Use this guide to learn how to add functionality to your bot by making use of other services' APIs. It only takes a few clicks.
Whereas TextIt's 'Wait for Response' RuleSet allows you to evaluate incoming responses according to various response rules, the 'Call Webhook' RuleSet allows you to send responses to an external service and either evaluate or reply with that service's response. For example, you can use a 'Call Webhook' RuleSet to POST a message to the Google Translate API, then reply with the translated message using a 'Send Message' action that contains a variable–starting with the '@extra' prefix*–that matches the translated message's key in the returned JSON object.
See for Yourself
Search the following bots on Telegram to interact with flows that make use of other services' APIs:
Oxford Wordsly, a bot that tests your English and Spanish vocabulary using a collection of APIs.
Purrington, a bot that provides cat facts.
Bandito, a bot that provides Spanish translations.
Using Webhooks
To get started, you'll need an API, a key to access it, and a sample request from that API's documentation. In the example below, we'll be using Google's geocoding API to verify addresses submitted by our contacts. Instructions for acquiring a key are usually front and center in the API's documentation:
The documentation states that we'll need to structure the request like so:
The request above dictates that, aside from our key, we'll just need to provide an address. To do so, we'll need to create a flow that asks the active contact for their address. We'll be using an open-ended 'Wait for Response' RuleSet labeled 'Address' to handle that response.
Next, we'll connect the 'Address' RuleSet to a 'Call Webhook' RuleSet. We can place the variable created by the 'Address' RuleSet in our request to ensure that it represents the address each contact submits.
Now we can use the simulator to inspect Google's response.
Google responded with a 200, meaning that our request was successful. Now we'll need to parse it's response for the fully formatted address. We can do so by clicking the highlighted 'webhook event' link in the simulator. The key we're looking for is 'formatted_address'.
Since this key is actually housed in an array under a key called 'results' (the 'results' array isn't visible in the image above), we'll need to place '.0.' in front of it to access it:
@extra.results.0.formatted_address
Finally, we'll need to account for failures. We can do so by connecting the 'Failure' category that the 'Call Webhook' RuleSet automatically creates to a message that prompts the active contact to try again.
Voilà, we've created a flow that collects and verifies our contacts' addresses using Google's Geocoding API. What will you build?
Tips
- If an API responds with minified JSON, you can expand it using this tool.
- This page is a great resource for publicly-available JSON APIs
Questions? Comments? Let us know! We love hearing from you.
