Free TextIt Hosting for Coronavirus Projects

In response to the global Covid19 outbreak, Nyaruka is offering free TextIt hosting to all initiatives aiming to help during this pandemic. Projects we support have already sent and received millions of messages answering questions posed by the public and we want to do our part in ensuring even more people can be reached in the weeks ahead.

If you are working on a project related to the Covid19 outbreak, you can create an account for free at https://textit.in/. Once you have built your system please reach out to us and we will add additional credits to your account to guarantee you can scale nationally.

Projects do not need to be health related, we have customers building takeout and delivery systems using TextIt to help avoid physical contact just as we have customers building informational bots to help spread information in communities. Every little bit can and does help!

Our team is ready and eager to help you with any questions you may have.

Please share this with any of your colleagues who might find it useful.

Stay safe, working together we will all get through this.

Fixing Missing Dependencies


In some cases, you might find that a flow depends on something that no longer exists. When this happens, you will see the action title in red (as seen above) to let you know that a flow issue is present. For example, you might be looking at a flow that references a contact field by using an expression like @fields.age. However, at some point you may have deleted the contact field for Age. 

When this happens, your flow will continue to run, however it might lead to unexpected results. In some cases, such as updating a contact field for a missing field, nothing will happen (other than the field will not be set). 

In other cases, it might be more noticeable. Perhaps you created a Send Message action that looked like the following example. In this case, it may cause some confusion as the value for @fields.volunteer_id would be left out.

After creating a node with a messing dependency, you'll see that the node itself turns red. If you click on the node to edit, you'll see a notification that says 'Cannot find a field for @fields.whatever_field_name

You will also see a new red tab appear to the right of the editor called 'Flow Issues'.

Click on the Flow Issues tab to get a full list of all the missing dependencies and click on each to be taken to the exact node in your flow.

Contact Fields are not the only things that can go missing and result in a missing dependency error. You may see this with a Contact Group that has  been deleted, a channel that no longer exists, or a variety of other things your flow may reference.


Want to learn even more about using TextIt? Check out our Help Center

Questions? Comments? Let us know!

Restricting Sending to International Numbers

Your channel's phone number may automatically allow sending messages to international numbers, which could cause carrier or aggregator fees to add up. To avoid international messaging charges, you can choose to restrict sending. 

First, navigate to your account page and scroll down to the phone number you'd like to restrict:

Next, click the 'Edit' button to change the settings:

Uncheck the box allowing sending to international numbers:



Want to learn even more about using TextIt? Check out our Help Center

Questions? Comments? Let us know!

Changing the Order of Featured Fields on the Contacts Page

When viewing your featured fields on the Contacts page, you will see that they are organized left to right starting from earliest creation date. In the example below, the contact field school id was created at an earlier date than  state.

To change how the contact field columns are viewed, first navigate to the Manage Fields page found within the Contacts tab:

Here, click on the 'Featured' folder to the left of the page:


You'll see a list of all featured fields. Hover over a field to click and drag to the position you'd like. 


Navigate back to the Contacts tab to see the contacts fields have rearranged to your specifications: 

Don't see a contact field in the list? First, make sure it's featured


Want to learn even more about using TextIt? Check out our Help Center

Questions? Comments? Let us know!

Using the Context Explorer

The Context Explorer feature found in the simulator within each flow's editor allows you to view and better understand all the variables available in your flow. The explorer gives a detailed breakdown of values and their expressions, which can be copied for use elsewhere.

To use the Context Explorer, first navigate to the flow's editor. In our example, we want to see all the available variables for a flow asking contacts to join a group of their choosing to earn a free coupon:

At the bottom right corner of the editor, we see the Simulator button:

By clicking the 'Run in Simulator' button, we will run a test contact through the flow up to whichever point in our flow we'd like to view. Here, we've run the test contact all the way through to the flow's exit, or end. 

We'll then click on the '@' symbol found at the bottom left of the simulator to view the Context Explorer: 

In our example flow's explorer, we can immediately see the test contact's telephone number, the global API key set in our account, how many inputs were received from the contact, the results of the flow, and the flow's run:

We can expand each value to view even more detailed information like when the contact was created, the language of the contact, their group membership, and more:

We can hover over a value and click the clipboard icon:

This will copy the expression for that value to the clipboard for use elsewhere:


Want to learn even more about using TextIt? Check out our Help Center

Questions? Comments? Let us know!

Sorting Contact Field View

By clicking on the column header of a featured contact field on your Contact page, you can change how the fields are sorted. 

For example, we can change how the fields are viewed to either sort youngest to oldest or vice versa:

This feature is useful in this case to see the breakdown of our contacts' ages to better organize our demographic information. 

Want to learn even more about using TextIt? Check out our Help Center

Questions? Comments? Let us know!

Adding a Topic to Your Facebook Messenger Flow

Facebook has updated their API to require that all messages sent to a contact after 24 hours have an appropriate 'tag', or what we call a 'topic'. 

Message tags allow you to send important and relevant 1:1 updates to contacts outside the standard messaging window of 24 hours after a contact's last message. 

By default your flows will use the NON_PROMOTIONAL_SUBSCRIPTION  tag for your outgoing messages which aren't replies, but support for this tag is being removed in March 2020. 

You can now select the tag to use when sending broadcast messages by clicking on the first message of your flow and navigating to the "Facebook" tab as seen at the top of the message node:

For our example above, we'll choose the 'Event' tag since our message pertains to an update for an upcoming event. This will then mark the message with that tag when it is sent. You only need to do this on the first message in your flow. 

It is important to note that as per Facebook policy, message tags may not be used to send promotional content, including but not limited to deals, offers, coupons, and discounts. Learn more about sending messages with tags as well as details on new and currently supported tags here.

Looking for information on how to create and submit your Messenger bot? See our guide

Want to learn even more about using TextIt? Check out our Help Center

Questions? Comments? Let us know!

Global Variables

Globals are shared values that can be referenced in flows, as well as broadcasts and campaigns, within your account referenced by @globals.value_name. They allow you to create a value once and use it repeatedly without having to reenter the value. Likewise, globals make updating a shared value much easier. Rather than manually changing a value everywhere it's used in your account, simply update the value found in your 'Globals' page. 

Say you have 5 different webhooks in your account that all use the same Airtable API Authorization key. By saving that key as a global variable, you can easily reference the key without having to look it up in your Airtable account every time you create a webhook.

How it works

We've got a flow where we want to retrieve data from a table in our Airtable account multiple times. This means we'll need to use more than one Call Webhook action, and each of those will need to be configured using the API Authorization key from Airtable. To avoid having to look up the key for each configuration, we'll create a global to save time.

Create the global variable

Go to your account page, then scroll down to to the @ globals section.

Here, you'll find your Globals page where you can create and manage your global variables.

To create a new variable, click the 'Create Global' button. Choose a name and enter the value. For our API key example, the value is the same value that we'd enter for the 'Authorization' header in our Call Webhook action in our flow.

Note that by clicking on the 'uses' link next to each global variable on your 'Globals' page, you can see every place your global is used. 

Use the global in a flow

After creating the shared API key global, we can reference it in all of our new Call Webhook actions in our Airtable flow. 

When we create each new Call Webhook node, we don't need to enter the text value of the Authorization header.

We can instead simply reference the value using the global variable we've created using @globals.api_key. Recall that we named the variable API Key when we created the global earlier. 

That's it! For any other webhook where we would also use the same Airtable API Authorization key, we don't need to look it up. We can easily enter the global instead. 

Note that globals can only be edited or updated within your Globals page and not within flows. 


Want to learn even more about using TextIt? Check out our Help Center

Questions? Comments? Let us know!

Adding Classifiers to a Flow

Classifiers let you interpret words and phrases into intents you can act on. Various services let you train your own classifier which you can then use in your flows to draw meaning from the unstructured text contacts send you.

We support the following classifier platforms:

  • Wit.ai is a Facebook owned natural language platform that supports up to 132 languages. The service is free and easy to use and a great choice for small to medium sized bots.
  • LUIS is a Microsoft Azure platform that lets you interpret natural language in your bots. It supports 13 languages and is a highly scalable paid offering.
  • Bothub is an Open Source NLP platform. It supports 29 languages and is evolving to include the languages and dialects of remote cultures.

Create your Bot

In our example, we've used wit.ai. Wit allows you to extract relevant pieces of information — or entities — from what your users might say to your app in a flow. Train your wit bot to understand what your contacts communicate and respond appropriately. Check out Wit's tester bot and help docs to see how it works. 

To get started, navigate to wit.ai and click on the 'Bots' button. Log in with either your Facebook or GitHub account. 


That's all it takes to create your first bot. Next, you'll need to train it. You'll teach your bot to extract entities (information) based on relevance. 

In the example below, our app will allow contacts to set reminders. Here, the contact is asking the bot to remind them to call the dentist the following day. We've matched the rules wit/reminderwit/contact & wit/datetime to their appropriate entities in the sentence. This will teach the bot to pull out similar data from free text and understand the contact's request. 

To better understand how to use Wit, be sure to follow their quick start guide!

Connect your Bot

After you've created and trained your bot, you're ready to integrate it into your account. Visit your account page and click the gear icon in the top right corner. Choose 'Add Classifier' from the dropdown menu:

Then choose your preferred service:

You'll need to authenticate your account to connect it. Find these details in the API section of your service's account page. In the case of Wit, we'll enter the bot's name, App ID & Access token:

Build your Flow

In the example above, we've built a flow to ask customers of a travel agency to send their inquiry. After asking a question like, "What can I help you with?", contacts will send unstructured free text captured in the flow using a 'Wait for Response' split action. We'll be sure to use 'has some text' or 'is not empty' to be able to collect the response from the contact.
 


Next, we'll use the 'Split by Intent' split action in the flow to run the response through the classifier (our Wit bot) and create rules to extract the intent from the text. You'll see a dropdown of all possible intents pulled from the training you've done with your bot. In our example, we're looking for a response with the entity "flight" that will tell us that the contact wants to book a flight with our agency. Remember, we've already trained our bot on wit.ai to understand this intent.

Say the contact responded to our first question with "Book a flight to Miami". The classifier will extract "flight", as programmed during training, and understand that the contact wishes to book a flight. Here's how that looks in the contact's message log:

We can see above that the bot has successfully extracted the entity "flight".

If you find that your bot doesn't understand the unstructured text from your contacts, continue training it so that it can continue to learn. 

Referencing entities in your flow

Within your flow, you can access the entities that are extracted from the classifier using the variable @results.classify.extra.entity_name. You can then work that into your reply message. This means that in our sample flow, we'll reference the entity using @results.result.extra.destination. Note that result is what we named our 'Split by Intent' result and destination is the name of the entity from our Wit bot training.

Here's how that looks:

Using the simulator to test the flow, we can see how we've pulled out the entity and referenced it using the variable @results.result.extra.destination and how it looks in our reply message to the contact:

What's the difference between 'has intent' and has 'top intent'?

Has intent will match if the intent is found with a higher confidence than specified in the rule. Has top intent is the same, but only if it is also the highest confidence amongst all intents.

Want to learn more about building flows? Check out our Help Center

Questions? Comments? Let us know!

Tracking Down Sending Errors

Occasionally, a message will not send properly or will not be received by a contact. When this happens, you can track down the exact error by checking the message log. 

View these logs on the platform by clicking on the document icon to the right of the message in the contact's history. 

In the log, you can see whether the message was sent by TextIt and passed to the aggregator, carrier, or social media channel up at the top. You can also see if the provider called back to report if the message was sent and delivered.  
 

In the message log above we can see the following:

  1. The recipient of the message.
  2. The direction of the message.
  3. The date and time the message was sent. 
  4. The status the message. In this example, it shows that Twilio returned the message as 'Delivered'. 

Last, in the box at the bottom, we can see that Twilio, the channel on which we sent the message, called back to TextIt saying that the message was delivered to the contact. 

If your message is shown as sent by TextIt but was not actually received by the contact, there is most likely an error occurring on the side of the aggregator, carrier, or social media app. Contact them with the logs you've viewed on TextIt to help them track down the problem. 

Failed Messages 

What if the message shows that it failed sending? When this happens, check the message log for error codes. 

In the example below, a message failed to send to a contact via a Telegram channel. Note that the message's status is listed as 'Error' and we can see that in the callback, there is an error code returned from Telegram. See a list of Telegram error codes here.

Other common causes of failed messages are improper telephone number configuration, such as not including a country code, or if the phone number turns out to be a landline. Note that for Twilio channels, the most common error is attempting to use a trial number rather than a purchased number. See a complete list of Twilio error codes here

You can also view failed messages by going to the 'failed' folder within the 'Messages' tab:

Clicking the document icon to the right of the messages in the failed folder will either take you to the channel error description or the profile of the contact to which the message was sent, depending on the status of the channel you used to communicate with them. Please include a link to the error or contact profile when requesting further support. 

Want to see more about troubleshooting delivery errors? Check out this article for more information.

Questions? Comments? Let us know!