Home / DialogFlow / Why Dialogflow webhook documentation is so sparse
DialogFlow

Why Dialogflow webhook documentation is so sparse

In the Dialogflow forums, you will see that people are constantly asking for help with webhooks. And if someone were to create a good webhook course, supply-demand economics suggests that they could make a tidy profit. So why isn’t there such a course?

The Exponential equation

I have mentioned it in forums before, but the challenge is with the number of variables involved.

As you create a moderately complex webhook, you need to choose three things:

  • the programming language
  • the database
  • the hosting platform/service

Since webhooks are intentionally designed to be extremely flexible, you can choose any suitable technology for any of these three choices. Naturally, people are most likely to stick to what they already know.

Let us suppose there are 10 different popular languages one could choose from. And suppose there are 10 different hosting platforms*. And 5 popular databases that can be used to store the data. That already gives us 10 x 10 x 5 = 500 possible combinations.

You may disagree with these numbers, but even if you tweak and reduce them, you will likely be left with at least 100 combinations.

The small differences do matter

Someone who has been programming for a while will point out that the differences between the choices are very minor. Most programming languages have easy to comprehend syntax. And you should be able to pick up the setup for these hosting platforms in a few days. And so on.

(Already, this means you are making it harder for people new to programming.)

But I think there is another issue. Here is a comment I received on my blog recently:

This seems like a minor issue. This person was able to get the original NodeJS webhook tutorial working. Instead of using the Google Cloud for the straight up deployment, they would instead like to use Firebase HTTP triggers. (To be clear, this article isn’t about this particular comment or commenter. What I am talking about is the challenge of creating documentation for webhooks).

Now we come to Firebase.

And Firebase Cloud Functions are basically these functions you can run without provisioning servers, which means they are really scalable.

And look at all the ways you can “invoke” these Cloud Functions

Obviously, Google has left no stone unturned here. 🙂

But it also means that those who are interested in using the Cloud Functions suddenly need to know, if only at a basic level, about 3-4 additional concepts. (You will probably safely ignore things like Crashlytics Triggers at this point).

Back to our commenter.

Suppose I would like to update my sample code to get it working for HTTP Triggers. How much effort does it require? Even if learning and doing it for myself might not take a long time, but there is usually a 3x time multiple when you try to write and teach the same concept.

Summary

So what should the people writing the documentation do? And what about those who try to create courses (like me)?

Unfortunately, I am not sure there is a simple solution here. I think this is just an inherent challenge with creating webhooks that are so flexible**. I have been postponing a very basic Webhook course I wanted to create for a few months now because I don’t think it is possible to do justice to the course in a reasonable amount of time (unless I charge, say $500 for the course).

* Containerization can probably help here

** Google is certainly nudging people towards a recommended approach by making the documentation predominantly use Google’s cloud services. The problem though, as you see in the different ways to invoke cloud functions – even Google’s own offerings are a fairly complicated mish-mash, and the documentation for these different offerings are often not caught up with the furious pace at which the services are being improved. In fact, I actually recommend people use the basic Python webhook tutorial on Heroku to get started with the basics – because it is very stable in terms of the documentation!

Related Posts

  • Hallo zusammen,

    ich benutze zur Zeit Dialogflow und Google Assistent, um bestimmte Standard Gespräche zu automatisieren. Was kann ich nutzen um eine Umleitung auf ein bestimmtes Telefon zu ermöglichen, wenn das automatische Gespräch nicht erfolgreich war ?

    Würde mich freuen, wenn mir jemand helfen könnte 🙂

    • From Google Translate:

      “Hello everybody,

      I’m currently using Dialogflow and Google Assistant to automate certain standard conversations. What can I use to redirect to a particular phone if the automatic call was unsuccessful?

      Would be glad if someone could help me 🙂”

      This looks like a pretty complex scenario, and I don’t know the answer. You should ask this question on the forum.

  • Thanks Aravind, I managed to make it, soon I will provide a full GitHub source got for it…

    but i’m still confused about a thing about a thing…
    after I managed to get it working for this API
    http://maps.googleapis.com/maps/api/geocode/json?address=cairo

    it works perfectly, if you open the link you will see that the JSON response is beautified…

    for other APIs using the same code method it doesn’t seem to work, and the only difference that all other JSON responses are not beautified… so eventually they return a Webhook error…

    I know it doesn’t make sense, but I found many using APIs and getting that error, they think the problem is that DialogFlow still having problems with APIs. but if that is true how did it work for Google Maps API

      • I don’t see why, I need ngrok really :/
        the same exact method is used for google maps api is the same I used on openweather(and other APIs).
        it’s just the one with google api works like a charm, while all other apis just don’t work…

        and the only difference between google Maps API and all other APIs is that Google’s API JSON Response is beautified :/ this is so weird :/

        tried to install json-beautify from npm, used it but it’s the same so i’m really confused about that :/

  • Can you create a “chatbot memory guide” in PHP? I have a dialogflow chatbot integration with a webhook in php. And I want to save context even if the user answer 3 hours later.

    Or maybe if he answer 3 hours later I say “*Answer*” but if he answer 20 hours later I say “hi again! *Answer*” To make more natural

    I dont user FB, slack… Is an integration in my own chat so my sessionID always is the same.

    • That’s an interesting question. I cannot get to it right now, but I have added a to-do item to write about this when I get time. A quick summary of the answer would be: you can save all your user interactions, along with your last output context, in your DB. Since you are using the REST API anyway, and you seem to have only a single user using the system, when user comes back and re-types a message, you set the last known context (saved in your DB) using the REST API and then send the user’s message over to Dialogflow. I haven’t tried it, but it should likely work.