Forem: Daniele

Build a low-code chatbot using Autohook and YAML

Daniele — Thu, 16 Apr 2020 17:56:15 +0000

Chatbots are useful to provide relevant and timely information via direct messages. Developers can build logic to create a ‘script’ that directs users to the relevant answers they’re looking for.
I’m amazed by the people coming together in this current crisis to help however they can. I wanted to do my part and hope that it inspires others to contribute too. Chatbots can be used to help people find information from reputable sources. In my previous tutorial, I used Autohook to reply to direct messages with little code. Still, you will need to define the flow between a user and a bot, and that logic is usually tailored for each project.

I wanted to build something that requires minimal coding, so that anyone could build a useful service. I created a low-code, bot framework that pulls together all the relevant bits:

It uses Autohook to receive direct message events
It defines a set of text files with the logic to reply to a user
It configures a welcome message for an account designed as chat agent
It uses the Twitter API to send a direct message to the user who contacted the chat agent

With this framework, I built a bot that provides regional information about COVID-19 for the US, Spain and Italy, which are severely affected by the current emergency. By chatting with the bot, you can get useful resources from local authorities, and find ways to donate.

The bot uses public domain information from the CDC, Italy’s Ministero della Salute (Ministry of Health) and the Spanish Ministerio de Sanidad, Consumo y Bienestar Social (Ministry of Health, Consumer Affairs and Welfare). The bot needs to adapt to the situation in each country; for example, people in Italy need a certificate to travel, and the bot should be able to provide the link to the official website to fill the form to Italian users.

The project is also configured to run either locally or on a remote server. You can find the full project on Glitch, and you can interact with the final result.

Setup your Twitter app

To get started, you need to set up a Twitter app and to have a valid developer account. We covered this process in my previous tutorial about Autohook. Read the section named “Your Twitter app” to learn more.

Building our flow

There seems to be no in-between when it comes to setting up the actual conversation flow. Developers either build custom logic with code, or they purchase access to sophisticated interactive workflow automation platforms. On Twitter, chatbots are equipped with quick reply options, so we can build a flow based entirely on the inputs from these quick replies.

By relying on quick replies, we can turn our chatbot into a finite-state machine; in other words our bot can be in exactly one state at any given time, and the number of states are predetermined (finite). This seems to be exactly what we need!

Each reply from the chatbot will have one or more quick reply option
The user can only tap one option per reply
Each option brings the bot to the next state
The state is basically our next message
Any user input from the keyboard is discarded; it will simply trigger a “do not understand” reply, and it will repeat the last message

I mentioned my bot is answering in three languages. How do we apply the finite-state paradigm to our flow? In this case, each language is a state, plus another state for the “do not understand” case (more about that later). Users can only select one option (a language in this case); any other input triggers a “do not understand” message, bringing the user back to the language selector.

In the diagram, each bubble represents a chat message from our bot, and each arrow is an input from the user. By giving our bot a finite-state mindset, we can be sure to articulate the full conversation.

Write, don't code

How do we translate that conversation into code? We don’t. Instead of writing code, we will write text files. Each file will contain one or more bubbles as defined in our diagram. Each bubble will list the options it supports. Each option will bring the user to the next state.
We will use the YAML format for our text files; this way we can specify tags and lists of options – which is exactly what we need to build our quick replies.

start:
  text: |
    🇺🇸 Hi! I'm a bot and I'll help you with resources on COVID-19. Please select your country.

    🇮🇹 Ciao! Sono un robot e posso aiutarti con risorse utili su COVID-19. Per favore, seleziona la tua nazione.

    🇪🇸 ¡Hola! Soy un robot y puedo ayudar con recursos utiles sobre la COVID-19. Por favor, selecciona tu nación.
  options:
    - label: 🇺🇸 United States
      description: Contains resources from CDC
      metadata: scripts/en-us/for-me.yaml#start
    - label: 🇮🇹 Italia
      description: Usa le linee guida del Ministero della Salute
      metadata: 'scripts/it-it/for-me.yaml#start'
    - label: 🇪🇸 España
      description: Con las lineas guias del MSCBS
      metadata: 'scripts/es-es/for-me.yaml#start'
do_not_understand:
  text: |
    🇺🇸 I'm sorry, I can't read what you type. Please try again by selecting one of the options instead of using your keyboard.

    🇮🇹 Mi dispiace, non posso leggere quello che scrivi. Per favore, prova di nuovo selezionando una delle opzioni anziché usare la tastiera.

    🇪🇸 Lo siento, no puedo leer lo que escribes. Por favor, intenta seleccionar una de las opciones en vez de escribir.

We then pass these files to our finite-state machine processor. The Agent module simply opens the file specified in the metadata field, gets the bubble with the name specified after the # character, and handles that over to the code that will send the direct message back to the user.

In practical terms, our language selector contains three options. When the user selects España, our finite-state machine will open the file scripts/es-es/for-me.yaml and look for a bubble named start.

class Agent extends EventEmitter {
  constructor() {
    super();
    this.script = null;
    this.file = null;
    this.entryPoint = 'start';
    this.state = {};
  }

  loadFile(file, state = {}) {
    [this.file, this.entryPoint] = file.split('#');
    this.entryPoint = this.entryPoint || 'start';
    try {
      this.script = YAML.load(this.file);
    } catch (e) {
      console.error('Exception:', e);
    }

    this.step(this.entryPoint);
  }

  currentStep() {
    return this.script ? this.script[this.entryPoint] : null;
  }

  setState(state) {
    this.state = Object.assign(this.state, state);
  }

  step(entryPoint = 'start', state = {}) {
    if (entryPoint.indexOf('#') > -1) {
      this.loadFile(entryPoint, state);
      return;
    }

    if (!this.script[entryPoint]) {
      throw Error(`No entry point named ${entryPoint} defined in ${this.file}. Add the entry point in your script file.`);
    }
    this.setState(state);
    this.entryPoint = entryPoint;
    this.emit('step');
  }
}

Send the message

The twitter_dm.js module contains the logic to send direct messages; here we’re simply wrapping the send logic from my previous tutorial in a separate module to keep things tidy.
The JSON payload for a direct message is quite verbose, so we added a MessageCreate class. It helps compose the JSON body easily, and it will also translate incoming JSON requests into a valid message. This can allow us to translate raw JSON directly into a chat bubble with no effort!

I don’t understand – is it really that easy?

The only thing left to handle is keyboard input. The chatbot will simply acknowledge its ignorance – it will send a message saying it doesn’t understand, then it will send the previous message again. How do we handle this case?

Our finite-state machine will once again help us. After all, we defined any other input to be just one case, so we will need to define that “do not understand” case as a bubble too. Because the keyboard input will not send metadata, we will have our agent fall back to that “do not understand” bubble when our code does not receive metadata. We then call our previous agent’s step again to display the options.

In the code, you can see how we're even localizing the message if the user has already selected a language!

We hope that you will dig in and take the code for a spin! As I mentioned, if you’d like to add other languages or enhance it further, you can find the full project on Github. If you add anything, submit a pull request! If you want to try it live you can interact with the final result.

I used several libraries and services beyond the Twitter API to make this tutorial, but you may have different needs and requirements and should evaluate whether those tools are right for you. Let me know if this inspires you to build anything!

Hey Siri, text my latest Tweet

Daniele — Thu, 21 Nov 2019 17:06:45 +0000

As someone whose first language isn’t English, I tend to find myself Tweeting and dreaming in English; many of my friends do not. And I'm too lazy to translate my Tweets.

I also happen to like iOS 13 a lot. Dark Mode looks fantastic, and I'm enjoying Memojis a little too much. But my favorite app has to be Shortcuts. It ships by default with iOS 13, and it's more powerful than ever. With Shortcuts, you can instruct Siri to do things for you, including tasks no other app can do.

Shortcuts is a true hidden gem; its power and ease of use allows you to build automations without writing a single line of code. The app is extremely powerful; among other things, it has a HTTP client and a JSON parser. This is all you need to connect to any API.
So I thought, what if I can translate my latest Tweet, and send it only to my friends? Shortcuts can translate for me, and I can use Twitter Developer Labs to get my Tweets. Labs is our program where we’re building our next API in the open by inviting developers to help shape the future of the Twitter API. You can test drive new features and even full endpoints before they are broadly released, and you can tell us what you like and we can improve through our feedback channel (we already shipped some features based on feedback from people like you). It's free and you can try it out now.
Here's what we're going to do:

Get access to Labs
Tell Shortcuts to generate a bearer token
Get our latest Tweet using Labs
Ask Shortcuts to translate the Tweet
Send an iMessage with the Tweet

🧪 Enter Labs

If you already activated Tweets and users you can jump to the next section.

For this tutorial, you need access to Labs and the API. First though, you will need a valid app – if you don't have one, you can apply on our Developer site.

Once you have an app, join Labs and follow the instructions (it only takes a minute). When done, you should see a list of endpoints:

In this tutorial, you're going to deal with Tweets and users, so select Activate for that row, and attach the app you want to enable (you can enable one app per endpoint, but multiple endpoints can be attached to the same app).
Now, go to your app list, locate the app you've just enabled for Tweets and users, and take note of the consumer key and secret.

🤖 Coding with no code

Now we'll start coding… With no code. Shortcuts allows you to assemble tasks together, and if you know how to use an API, it's even more flexible.

Open the Shortcuts app (if you don't have it, you can download it for free from the App Store). Tap Create Shortcut.

On the first screen, tap Add Action. You'll see a lot of options, but you simply need a place to store your configuration (your credentials and your Twitter username). To do so, you're going to use a dictionary:

Configure the dictionary with three keys:

consumer key with your consumer key
consumer secret with your consumer secret
username with your Twitter username (without @)

In my case, it looks like this:

Now let's request a Bearer token. To do so, we need to call the Twitter API by combining your consumer key and secret with a colon, for example, consumer key:consumer secret, then encode in base64, and send the resulting string in the Authorization header. In Shortcuts, we simply have to add a text component to combine the credentials, then add a Base64 Encode step:

Next, create your actual request. Like I said, Shortcuts contains a full HTTP client, so for this step you just have to fill in the blanks:

Select Get contents of URL.
Use https://api.twitter.com/oauth2/token as the URL.
Tap Show more.
In Method, select POST.
In Headers, add Basic, then select ⚙️ Base64 Encoded
In Request Body, select Form.
Add a field called grant_type. Its value should be client_credentials.

Shortcuts has built-in JSON support. Our response will be JSON, so all we have to do is to tell Shortcut to retrieve the access_token field. Just add a Get Dictionary Value step after your request:

Get your latest Tweet

You’re now ready to get your latest Tweet, and Labs is going to help us a lot. In Tweets and users, there are two API endpoints (one to get Tweets, one to get users). In this case, you're going to use the users endpoint, because it always returns the ID of the most recent Tweet from the users you're requesting. But wait, you need the full Tweet, not just its ID! How can you avoid making another request just to get the full Tweet?

Thankfully, one of my favorite Labs features is going to help you a lot here. It's called expansions, and it allows you to get a full object instead of its ID. It works like this:

If I request /labs/1/users?usernames=i_am_daniele I get my user and most recent Tweet ID back
If I request /labs/1/users?usernames=i_am_daniele&expansions=most_recent_tweet_id I get my user and my most recent Tweet back (including its text!)

So now you’re going to create two steps. The first is a simple Get value for username from the dictionary you created at the very beginning. The second step is another Get contents of URL step configured like this:

Get contents of https://api.twitter.com/labs/1/users?usernames= Dictionary value &expansions=most_recent_tweet_id (yes, you can combine strings and variables together)
Tap Show more
Add a Header named Authorization. Its value should be Bearer (leave a space after Bearer)
Tap the magic wand icon on your keyboard, scroll back up a little, then tap on the "Dictionary value" label from "Get value for access_token in Contents of URL".

Let's add these next steps to get the actual Tweet text:

🇺🇸🇪🇸 Translate

Now that you have your Tweet, you can ask Shortcuts to translate it. The app is integrated with Microsoft Translator, so all you have to do is to add the Translate Text with Microsoft block to your workflow.

💬 ¡Enviamos!

Now it's time to send your text. First, combine the translated Tweet with a URL via a Text snippet, and then add a Send Message block. You can disable Show More -> Show when Run so your action runs seamlessly.

If you have Hey Siri enabled, try saying "Hey Siri, text my latest Tweet" to always be in touch with your friends, no matter what the language of your Tweets!

How to build a complete Twitter autoresponder in less than 100 source lines of code with Autohook

Daniele — Mon, 26 Aug 2019 23:17:54 +0000

This tutorial was originally published in the Twitter Developer website

The Account Activity API is one of the most versatile APIs in the Twitter Developer Platform. With this API, people can allow your app to get notifications about their activity on Twitter. What’s best, it uses webhooks to deliver real time updates.

Developers can achieve a lot with the Account Activity API. For example, companies can use this API to get a sense of how the global conversation is unfolding around their products and services. A popular use case is with customer service, where your favorite brands can reply to your Direct Messages in real time, and determine the best next action. This usually involves using the Account Activity API, configuring a webhook, figuring out OAuth, and understanding how to send back a message using additional Twitter APIs.

This would sound like quite the task, if you didn’t have the right tools. Thankfully, Autohook is here to make things extremely easy for you.

Autohook is a Node.js module and a command line tool that sets up webhooks for you. This way, you can spend zero time figuring out how a webhook works and instead focus on building awesome things on Twitter.

Autohook makes things very easy — so easy that you can automate a DM conversation on Twitter in less than 100 lines of code. We’ll build a simple autoresponder that’ll greet whoever Direct Messages your user. Here’s what we’re going to do:

We’ll set up a project, including a Twitter app enabled with an Account Activity environment
We’ll set up Autohook, so it will do all the hard work for us
We’ll build the logic to only respond to incoming Direct Messages
We’ll add a way to show messages as read
We’ll show a typing indicator before sending the message
We’ll send back a sample autoresponder message

Your Twitter app

First things first: in order to use Twitter’s Account Activity API, you will need to create an app on Twitter, and give it the Read, write, and Direct Messages permission. You also need to have a valid development environment assigned to this app. Chances are you’ve already done this: if so, you should see something like this in your dev environments page:

If you don’t already have a dev environment created, simply click Set up dev environment, type a label and assign it to an app. The label can be anything, but make sure you remember it because you’re going to need it for later.

You will need to get your access tokens from your Twitter app dashboard. From the app that contains the environment you just created, click Details, then click Keys and tokens. Make a note of the values reported under:

API key
API secret key
Access token
Access token secret

Create a file in your home folder called .env.twitter, and add the values you found in that page, plus your environment label:

TWITTER_CONSUMER_KEY=Details ➡️ API key 
TWITTER_CONSUMER_SECRET=Details ➡️ API secret key 
TWITTER_ACCESS_TOKEN=Details ➡️ Access token 
TWITTER_ACCESS_TOKEN_SECRET=Details ➡️ Access token secret 
TWITTER_WEBHOOK_ENV=Your env label

Developers are often confused by consumer keys and access tokens. Long story short, think of those as if they were encrypted username and passwords. A consumer key/secret pair are identify your app, while access tokens are user credentials. This means your consumer key/secret do not change, but your access token/secret changes based on the user who’s authenticating with your app.

You’ve probably noticed that if you’re the owner of your own app, TWITTER_ACCESS_TOKEN and TWITTER_ACCESS_TOKEN_SECRET identify yourself. If that’s the case, you don’t really have to go through OAuth to identify yourself – we already generated those tokens for you (keep that in mind, it’s going to come in handy later).

Install Autohook

Next, we’ll install Autohook. Its package is available from both npm and Yarn.

npm i -S twitter-autohook

I almost wish there were more steps, but that’s it. Autohook is that easy!

Create a new project

We’ll start with a new project. We’re setting it up in your home folder, but naturally it can live anywhere:

mkdir ~/autohook-tutorial
cd autohook-tutorial

Let’s create a file named index.js. We’ll add code to call Autohook and make sure everything is configured as intended. Just so we can start with a clean environment, this code will remove all existing webhooks from your environment. If you don’t want to lose your existing webhooks, choose a different dev environment from your developer dashboard. As an alternative, you can remove the call to removeWebhooks(), and replace start() with startServer().

Save and run your file. You should see something similar to this (note that your URL will be different, and so will be your subscribing username):

$ node index.js
Getting webhooks…
Removing webhooks…
Removing https://ce085a0d.ngrok.io/webhook…
Registering https://e3fd0ff6.ngrok.io/webhook as a new webhook…
Webhook created.
Subscribed to i_am_daniele's activities.

Behind the scenes, Autohook handled OAuth for us. It also ran a development server with logic to create a webhook and to validate the CRC signature. And because we provided your access token/secret, it also subscribed your app to listen to your user’s activity (it did come in handy)!

What can go wrong at this point? The most common pitfall is that the authenticating user won’t authenticate. Remember, users need to authorize your app before it can access their activity; if you’re trying to authenticate a test user (or even better, if you’re asking a friend to help you test your app), make sure they’re authenticating using Sign In With Twitter and the 3-legged OAuth flow. Autohook’s got your back – you can find a sample implementation on the project’s page.

If you bump into an error, most likely your credentials are not set correctly; check your .env.twitter and try again. If you’re still stuck, come visit the Twitter Community forums and we’ll be more than happy to help you out!

Detect and filter incoming events

Now that Autohook took care of the underlying wiring, it’s time to focus on our app logic. The Account Activity API can ping your webhook with many activity types, so it’s important we only react to the activity type related to an incoming message.

Since you’re using Autohook, you can listen to an incoming event listener – The event name is just event. Add this right before the call to removeWebhooks():

If you run your code now, nothing may seem to happen at first. But try and like a Tweet and something like this will show up in your Terminal:

You received an event! { for_user_id: '102010879991606016',
  favorite_events:
   [ { id: '92274d54c83ff07669999a00cad3e835',
       created_at: 'Fri Aug 02 21:54:13 +0000 2019',
       timestamp_ms: 1564782853144,
       favorited_status: [Object],
       user: [Object] } ] }

Because your app subscribed to your user’s activities, we received that activity in realtime. The object is always starts with for_user_id, which indicates a user ID (if you subscribe to multiple users, this is how you know which user this activity belongs to). The actual activity is described by a dictionary key. In this case, we received a key named favorite_events because we just liked a Tweet. There are many activities, like tweet_create_events, follow_events, and direct_message_events just to mention a few. In Autohook, these values will all be event keys in your event object from the listener. So if we want to listen to direct messages only, all we have to do is to explicitly detect those events:

webhook.on('event', async event => {
      if (event.direct_message_events) {
        await sayHi(event);
      }
    });

In this case, we will only process direct message events, and we’ll send the details to a function named sayHi(). This function will process the event and shoot a DM back waving hi to any incoming direct message!

Say hi 👋

We'll create a message to wave hi back to our friend who just messages us. But how do we know who’s the sender, and how can we be sure this message is directed to our account? Thankfully, the Direct Message event will contain full details about both parties involved in the conversation. You already have the OAuth credentials of the recipient (yourself), which is all you need to send a message back by means of sayHi(). The logic for this function is straightforward:

We’ll double check that the Direct Message event is valid and was intended for to your user. You don't really need to do this since this code will only work with your user credentials, but it will be useful to implement in case you want to expand your code to make it say hi for other accounts.
We’ll only listen to incoming messages (outgoing messages generate an activity too, and we want to filter those out otherwise we’ll run into an infinite loop).
We’ll say hi!

To check that the message is valid, we’ll need to check that the message object exists and contains a message_create key. This key contains all the relevant details about the message, including the sender and recipient IDs, and the message itself. We’ll also check the sender and recipient’s details, and if they’re the same, it means you are sending a message to yourself. If this happens, the autoresponder we’ll say hi to you, which in turn will cause the autoresponder to say hi to you, which in turn will cause the autoresponder to say hi to you… causing an infinite loop. It’s actually easier done than said:

  // We check that the message is a direct message
  if (!event.direct_message_events) {
    return;
  }

  // Messages are wrapped in an array, so we'll extract the first element
  const message = event.direct_message_events.shift();

  // We check that the message is valid
  if (typeof message === 'undefined' || typeof message.message_create === 'undefined') {
    return;
  }

  // We filter out message you send, to avoid an infinite loop
  if (message.message_create.sender_id === message.message_create.target.recipient_id) {
    return;
  }

All we have to do next is to prepare the request body for the message reply and send it as using the Direct Messages API. The request body of this API has the exact same format of an Account Activity message response, which makes it easy to consume and produce.

  // Prepare and sent the message reply
  const senderScreenName = event.users[message.message_create.sender_id].screen_name;

  const requestConfig = {
    url: 'https://api.twitter.com/1.1/direct_messages/events/new.json',
    oauth: oAuthConfig,
    json: {
      event: {
        type: 'message_create',
        message_create: {
          target: {
            recipient_id: message.message_create.sender_id,
          },
          message_data: {
            text: `Hi @${senderScreenName}! 👋`,
          },
        },
      },
    },
  };
  await post(requestConfig);

This is it! Run your code and ask a friend to send you a message. You should see an incoming message, followed by an automated direct message:

Mark as read and typing indicator

Our code so far is about 80 lines of code, so we have plenty of room to implement all the fancy things an autoresponder can do. Direct Messages on Twitter can indicate when a message has been read (it’s the blue check next to the message timestamp). Since our autoresponder will read an incoming message for us, it would be nice to tell the sender our autoresponder read our message and that it’s about to reply.

Because the message body doesn’t have to be sophisticated, you will send these POST requests as form encoded, rather than sending raw JSON data like we did before.

To get the read check mark, we’ll simply extract the message ID from the activity we received earlier. Just like before, we’ll create the appropriate request body to send it to the Mark Read endpoint:

async function markAsRead(messageId, senderId, auth) {
  const requestConfig = {
    url: 'https://api.twitter.com/1.1/direct_messages/mark_read.json',
    form: {
      last_read_event_id: messageId,
      recipient_id: senderId,
    },
    oauth: auth,
  };

  await post(requestConfig);
}

Similarly, we’ll now display a typing indicator which will present in the Direct Message window as a bubble with three dots. Since this is just an animation, there is no message attached to it; we will simply need to pass the ID of the person we want to show this bubble to the Indicate Typing API call.

async function indicateTyping(senderId, auth) {
  const requestConfig = {
    url: 'https://api.twitter.com/1.1/direct_messages/indicate_typing.json',
    form: {
      recipient_id: senderId,
    },
    oauth: auth,
  };

  await post(requestConfig);
}

You're all set! The complete code should look like this:

Time to say bye

And there you have it! Because you didn’t have to deal with the complexity of webhooks and authentication, you may have noticed that you just wrote the entire code in less than 100 lines! This has been a quick and easy way to explore the power of the Account Activity API, and a great starting point for your next 100 lines of code.