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!

Sending Airtime with DT One

The action Send Airtime enables you to transfer airtime to prepaid phones on over 550 mobile operators across 160 countries through one single API connection with DT One, formerly TransferTo.


Enabling Airtime Transfer

After setting up your account with DT One, navigate to your TextIt account page and scroll down to the DT One integration section:

Here, enter your DT One login and API token, found on the Developer page in your DT One account

Using the 'Send Airtime' Action in a Flow

First, create a new node and choose 'Send Airtime' from the dropdown menu of actions:


Next, select the currency, amount to send, and name the result to be able to reference it later. 

The editor will automatically look up the available currencies that can send to your contact's phone number through DT One. The platform will pick the biggest amount less than or equal to what is requested in the flow.


The 'Send Action' node you've created will have two connections, 'Success' and 'Failure':

If the transfer was successful, the contact will pass through 'Success' and you may choose to send a confirmation message. If the transfer experiences an error, the contact will pass through 'Failure'. If this happens, you could use actions such as sending the contact a message, adding a label, adding the contact to a group, sending yourself or a team member an email, and more

In our example, we've chosen to send the contact a confirmation message when the transfer is successful and an email to the team leader when a failure occurs:

In our email to the team leader, we've included the contact's telephone number. You can include saved variables and flow results collected in the flow up to this point to reference your contact's information. See how to use those variables here.

That's it! Contacts who pass through this node in a flow will receive the amount specified by your Send Airtime action.

Viewing your Transfer Logs

We provide a log of your transfers so you can review completed attempts and troubleshoot failures. To access these logs, navigate to your account page and scroll down to the DT One section, then click the 'Transfer Log' button:


As always, we appreciate your feedback. Questions? Comments? Let us know!




TextIt Used in Case Study to Prevent Postpartum Smoking Relapse

Researchers at the Cluj School of Public Health at Babes-Bolyai University in Cluj-Napoca, Romania used TextIt to deliver SMS interventions to prevent smoking relapse in participants after giving birth. 

The project sought to, "develop, implement, and disseminate effective and sustainable interventions to prevent and reduce smoking in families over their reproductive life span". The study focused on a group of women who quit smoking during pregnancy and their partners. The participants began to receive SMS interventions starting immediately after giving birth and for 6 weeks postpartum. 600 messages were developed and loaded into the TextIt platform to be sent out in flows and sub-flows each day of the 6-week intervention. 

We spoke with Andreea Hoștină, PhD(c), a research assistant who worked on the project's team, some questions about the group's experience using TextIt in their case study: 

How did you and your team learn about TextIt?

Andreea: We needed a platform that could help us deliver the SMS part of our intervention. We reviewed the literature and this is how we came across TextIt.

Why did you ultimately choose to use TextIt in your case study?

Andreea: When it came to deciding, TextIt seemed to offer us the tools that we needed. Another advantage was the customer support that was always prompt and eager to help us.

What benefits did you find in using the platform?

Andreea: The platform is very user-friendly and allows us to control the SMS delivery very well. All the functions are explained in the tutorials, and if you encounter some other difficulties, the team is always finding solutions.

Would you recommend using TextIt in other research/case studies and why?

Andreea: Yes, I would recommend TextIt for other studies because it is easy to use, the payment scheme is clear for everyone, and the team behind the platform is very nice and professional. To sum up, TextIt is offering the necessary tools to implement any SMS-based intervention.

To learn more about the project's design & methods, team of researchers, and publications, visit the Cluj School of Public Health's website here

It is important to note that this study was supported by a grant of Ministry of Research and Innovation, CNCS - UEFISCDI (project number PN-III-P4-ID-PCE-2016-0632, within PNCDI III).

Introducing Quick Reply Support for IP Messaging Channels

TextIt now supports quick replies, a feature that enables you to provide contacts on IP messaging channels such as Facebook Messenger, Viber, Telegram or LINE a predefined set of responses. 

Whereas simple text is the foundation of any mobile messaging experience, quick replies allow you to enhance the experience by presenting a collection of options to the message recipient. When one of these options is tapped, the set is replaced with a single text message which is then sent to your flow. 

Usage

To add quick replies to a message, simply click the dialog icon beneath TextIt's message composition form. 

These options will then appear for anyone who interacts with that flow. You can even test them yourself in the simulator. 

Quick replies are handled just like regular text, so you can continue to structure your RuleSets as you normally would.

Considerations

Note that your end users aren't limited to the quick replies you've prescribed; they can respond with their own text if they'd like. It's important to consider this when adding RuleSets for questions that include quick replies.

There you have it. Questions? Comments? Let us know! We value your feedback.

Link Anyone to your Facebook Messenger Bot with M.me Links

Just over a year ago, we announced TextIt's Facebook Messenger channel. Facebook Messenger wasn't the first non-SMS channel we added to TextIt, but it quickly became the most popular. Millions of people around the world prefer Facebook Messenger to SMS. Moreover, messages aren't limited to 160 characters and your contacts "numbers" aren't likely to change. This article introduces a new feature, triggers for M.me referral links, that makes it easy to share your Facebook Messenger bot with others and craft their experience once they're on Messenger. Note sure where to begin with Facebook Messenger? Let us know, we're happy to help! 


M.me links are a convenient way to share your Facebook Messenger bot, and they're simple to use: Facebook gives each page a link in the format https://m.me/PAGE_NAME, e.g. https://m.me/textitin. When a user clicks your link, they'll get taken to Messenger where they'll either start a new conversation with your bot via the 'Get Started' button or continue a conversation they started previously.



This is great, but what if you want to assign flows to the links you send out? Doing so is as simple as defining a reference parameter and appending it to your link in the format https://m.me/mybot?ref=myparam, e.g. https://m.me/textitin?ref=join. Next, go to the triggers page in your TextIt account, select the 'Start a flow when Facebook refers a contact' trigger, and enter your reference parameter ('join' in our case) in the 'Referrer Id' input. 



Considerations

  • If you have configured a conversation trigger for your page (triggered when a user first interacts with your bot and taps the 'Get Started' button), the M.me referral trigger will take precendence when the user taps the 'Get Started' button. 
  • If a user already has an open conversation with your bot in Messenger, they are not shown the 'Get Started' button when they tap your M.me link. Instead, the person will be sent directly to the conversation and, if you have an M.me referral trigger configured, start the flow of your choice. 
  • You can change your M.me link on your page's 'About' section (admins only). 

Questions? Comments? Let us know! We value your feedback. 

Troubleshooting Common SMS Problems

Text messages seem like a sure thing, right? We tend to send them off without thinking twice about their status or delivery order. We expect them to be delivered moments after we sent them exactly as they were authored. As it turns out, SMS isn't so simple under the hood. So in this article we're going to discuss steps you can take to troubleshoot common SMS issues. 

Message Splitting

Texts are split into a series of messages at the carrier level when they exceed their character limit (160 characters for messages that contain only the GSM character set; 70 characters for messages containing one or more non-GSM characters, like emojis 👍). Here's a tool you can use to determine whether or not your message will be split, and how many segments it will be split into. 

Delivery Order

Once a message is split, it's at risk of being received out of order. For example, if the last segment in the series is smaller than the first two, it may get to the end user first since the shorter message is sent the fastest. You can get around this by pre-splitting your messages in your flows and applying a label to indicate the order in which they should be read. 

Undelivered Messages

Android Relayer Channels

If you have an Android device, TextIt's Android channel enables you to send and receive messages anywhere you can acquire a local SIM card. Simply download the TextIt Android application on your phone and connect it to your account, and you're good to go. 

An Android channel will experience sending issues if:
  • the phone doesn't have a steady internet connection
  • the phone doesn't have a strong cellular connection
  • the Nyaruka TextIt Android app is toggled to "paused"

Log into your account, navigate to your account page, and then click your Android channel to view performance stats: 

Twilio Channels

If you're using a Twilio channel and one or more of your messages wasn't delivered, you may be encountering one of the these sending errors

To view your error and sending logs, navigate to your account page and click your Twilio channel: 

Next, click either the "Sending Log" button or "View Log" link to view bring up your sending log: 

You can use your sending log to isolate the issue and make the necessary adjustments. In the log pictured below, the user connected their trial Twilio number to TextIt and sent messages to a contact whom they hadn't verified through their Twilio account

Others

If you suspect your channel is have trouble delivering messages, click into the log we provide you. You'll find receipts for each request we made, and if an error has occurred you'll see an error code you can bring to your channel provider's attention. 

If you aren't sure where to look or you aren't able to identify the issue, let us know! We're hear to help 

Questions? Comments? Let us know! We value your feedback. 

Look Up Phone Numbers with Twilio's Lookup API

Have you ever wanted to retrieve additional information about a phone number? Perhaps you'd like to know whether a number is a land or mobile line. Maybe you'd like to know the caller's name or carrier. If you have a Twilio account, you've got access to an API that gives you access to all of this information and more. In this article, you'll learn how to use TextIt's webhook step to retrieve information about a number within a flow. 

Webhooks

A webhook is an HTTP callback: a POST request that occurs when something happens (a simple event notification). A web application implementing webhooks will POST a message to a URL when something happens, and this is exactly what TextIt does when a contact reaches the 'Call Webhook' step in a flow. We can use this special step to make requests to Twilio's Lookup API. 

Setup

First, you'll need a Twilio account. Next, grab the Account SID and Auth Token from its settings page. We'll be plugging these values into the new 'Headers' section of the webhook step. (New to TextIt? Use this guide to connect a Twilio number to your account and start sending). 

Credentials in hand, head over to base64encode.org to apply a special type of encoding that Twilio expects for this sort of request*. Simply input your Account SID and Auth Token separated only by a colon, e.g. ADa19ehc8fb23d2515:d09a32e56d8512685, and click the 'Encode' button. 

*Twilio uses a form of authentication called 'Basic Auth'. Basic Auth requires incoming user credentials to be base64 encoded. 

Copy the output and navigate to your TextIt account. Create a flow, select the 'Call Webhook' RuleSet, click the blue 'Additional Options' link, and create a header whose key is 'Authorization' and value  is 'Basic' plus your encoded Twilio credentials: 

Finally, manipulate to the URL to suit your needs. The expression @contact.tel_e164 will resolve to the active contact's number, but you can change it to another number if necessary. You can also change the 'type' query parameter to be 'caller-name'. 

https://lookups.twilio.com/v1/PhoneNumbers/@contact.tel_e164?Type=carrier

Results


You'll receive a JSON object like the one above, and you can access any of it's values using the @extra expression. For example, @extra.carrier.type will give you the value of the 'type' key and @extra.carrier.name will give you the name of the carrier. 

If you want your flow to evaluate the contact's carrier's type, you can add a 'Split by Expression' RuleSet like this one: 


The resulting flow might look something like this (landlines are exited): 

Considerations

  • Twilio does impose a small, pay-as-you-go fee for carrier and caller name lookups, more here
  • You can also pass basic auth credentials through the URL itself, e.g. https://ADa19ehc8fb23d2515:d09a32e56d8512685@lookups.twilio.com/v1/PhoneNumbers/@contact.tel_e164?Type=carrier


Questions? Comments? Let us know! We value your feedback. 

SMS Messaging Best Practices

From research study delivery to customer interaction, SMS messaging has become one of the most effective ways for organizations of every kind to both collect and disseminate information. Use this short guide to ensure that your organization's SMS messaging system adheres to best practices as dictated by the United States telecommunications industry.  

SMS traffic in the United States is governed by the Telephone Consumer Protection Act (TCPA), which dictates how and when enterprises and consumers can exchange messages. If your organization complies with the TCPA, you're probably in good shape, but you may be wondering, "is there anything else I should be considering?"  That bit is dictated by CTIA – The Wireless Association, an advocacy group representing the U.S. wireless communications industry as a whole. This guide serves to break CTIA's messaging recommendations into a short, clear guide to engaging in consumer-oriented messaging while simultaneously preventing the transmission of unwanted messages.

P2P vs A2P

It's important to first distinguish between the US telecommunications industry's person-to-person (P2P) and app-to-person (A2P) messaging definitions. 

P2P

P2P covers low-volume messaging, whether the participants are (a) individual wireless consumers or (b) wireless consumers and consumers of cloud-based messaging services or enterprises (e.g. TextIt). These exchanges must conform to the CTIA's "typical human operation" classification, which covers situations in which: 

  • No more than 60 messages are sent per minute. 
  • No more than 1,000 messages are sent per day. 
  • No more than 200 unique recipients are reached in total. 
  • The average ration of incoming to outgoing messages is typically 1:1, with some wiggle room. 

When wireless messaging traffic meets these classification criteria, it is considered to not exhibit the characteristics of unwanted messaging. 

A2P

At this time, CTIA views A2P to be all messaging traffic that does not meet its P2P criteria. It's both the type of traffic that the TCPA governs and the subject of this guide. At minimum, A2P traffic should: 

  • Seek the consumer’s express consent to receive informational and/or marketing messages.
  • Give the consumer the ability to revoke consent.

The CTIA sees the following use cases as appropriate for A2P traffic: 

  • Enterprises texting multiple consumers simultaneously. 
  • Call center scenarios 
  • Alerts and notifications 

Best Practices

Send via Short Codes

Short codes are 5 or 6-digit numbers typically reserved for organizations that need to communicate with consumers at a high volume. Use cases include flight delays, banking account alerts, delivery notifications, etc. They're designed to couple higher-volume SMS traffic with built-in consumer protections. As such, you must apply for a short code and go through a review process in order to obtain one. Fortunately, Twilio, our recommended SMS, MMS & IVR channel provider, helps customers through that process

Incorporate Toll-Free Numbers

If you aren't able to obtain a short code, consider toll-free numbers. They're only slightly more expensive than the standard mobile virtual numbers you might purchase from Twilio, but they've got two advantages: 
  • Your contacts don't incur a fee when sending to a toll-free number. 
  • They send 3 messages per second as opposed to standard numbers, which send at a rate of 1 message per second. This cuts down on the time it takes to deliver message broadcasts, and generally improves the speed of two-way interactions.  

Bundle your Numbers

Twilio provides a message service feature called Copilot that enables you to dedicate multiple Twilio numbers to a single TextIt channel, and improve SMS delivery with phone number intelligence features like: 

  • Scaler - distribute messages across a group of phone numbers to reach large audiences in a short amount of time.
  • Geo-Match - create a local experience by automatically using local phone numbers that match country and area codes to your end-user's personal number.
  • Sticky-Sender - send messages with the same recognizable phone number to create a consistent experience and maintain conversation history.
  • Reroute - if you're using a short code, you Twilio will automatically revert to standard long-code phone numbers when a carrier is unable to receive messages from short codes.
With a Twilio messaging service connected to your TextIt account, your messages will be routed intelligently to ensure you're adhering to best practices. Here's a guide to setting that up

What are your thoughts? Let us know. Your feedback is important to us.