Writing our own Haskell code using only simple libraries is fun. But we can’t do everything from scratch. There are all kinds of cools services out there to use so we don’t have to. We can interface with a lot of these by using APIs. Often, the most well supported APIs use languages like Python and Javascript. But adventurous Haskell developers have also developed bindings for these systems! So in the next few weeks, we’ll be exploring a couple of these. We’ll also see what we can do when there isn’t an out-of-the-box library for us to use. This week, we’ll focus on the Twilio API. We’ll see how we can send SMS messages from our Haskell code using the library. We’ll also write a simple server to use Twilio’s callback system to receive text messages and process them programmatically. You can follow along with the code here on the for this series. twilio Github repository Of course, none of this is useful if you’ve never written any Haskell before! If you want to get started with the language basics, download our . To learn more about advanced techniques and libraries, grab our ! Beginners Checklist Production Checklist Setting Up Our Account Naturally, you’ll need a Twilio account to use the Twilio API. Once you have this set up, you need to add your first Twilio number. This will be the number you’ll send text messages to. You’ll also see it as the sender for other messages in your system. You should also go through the process of verifying your own phone number. This will allow you to send and receive messages on that phone without “publishing” your app. You also need a couple other pieces of information from your account. There’s the account SID, and the authentication token. You can find these on the dashboard for your project on the Twilio page. You’ll need these values in your code. But since you don’t want to put them into version control, you should save them as environment variables on your machine. Then when you need to, you can fetch them like so: fetchSid :: IO StringfetchSid = getEnv “TWILIO_ACCOUT_SID” fetchToken :: IO StringfetchToken = getEnv “TWILIO_AUTH_TOKEN” Sending a Message The first thing we’ll want to do is use the API to actually send a text message. We perform Twilio actions within the monad. It’s rather straightforward to access this monad from . All we need is the function: Twilio IO runTwilio’ runTwilio’ :: IO String -> IO String -> Twilio a -> IO a The first two parameters to this function are actions to fetch the account SID and auth token. We've already written those. Then the final parameter of course is our action. IO Twilio sendMessage :: IO ()sendMessage = runTwilio’ fetchSid fetchToken $ do ... To compose a message, we’ll use the constructor. This takes three parameters. First, the “to” number of our message. Fill this in with the number to your physical phone. Then the second parameter is the “from” number, which has to be our Twilio account’s phone number. Then the third parameter is the message itself. To send the message, all we have to do is use the function! That’s all there is to it! PostMessage post sendMessage :: IO ()sendMessage = runTwilio’ fetchSid fetchToken $ do let msg = PostMessage “+15551231234” “+15559879876” “Hello Twilio!” _ <- post msg return () And just like that, you’ve sent your first Twilio message! Note that it does cost a small amount of money to send messages over Twilio. But a trial account should give you enough free credit to experiment a little bit. Receiving Messages Now, it’s a little more complicated to deal with incoming messages. The first thing we need to do is create a webhook on our Twilio account. To do this, go to “Manage Numbers” from your project dashboard page. Then select your Twilio number. You’ll now want to scroll to the section called “Messaging” and then within that, find “A Message Comes In”. You want to select “Webhook” in the dropdown. Then you’ll need to specify a URL where your server is located, and select “HTTP Post”. For setting up a quick server, I use Heroku combined with this that works with Stack. I’ll go into that in more depth in a later article. But the main thing to see is that our endpoint is . nifty build pack /api/sms With this webhook set up, Twilio will send a post request to the endpoint every time a user texts our number. The request will contain the message and the number of the sender. So let’s set up a server using Servant to pick up that request. We’ll start by specifying a simple type to encode the message we’ll receive from Twilio: data IncomingMessage = IncomingMessage { fromNumber :: Text , body :: Text } Twilio encodes its post request body as . In order for Servant to deserialize this, we’ll need to define an instance of the class for our type. This function takes in a hash map from keys to lists of values. It will return either an error string or our desired value. FormURLEncoded FromForm instance FromForm IncomingMessage where fromForm :: Form -> Either Text IncomingMessage fromForm (From form) = ... So is a hash map, and we want to look up the “From” number of the message as well as its body. Then as long as we find at least one result for each of these, we’ll return the message. Otherwise, we return an error. form instance FromForm IncomingMessage where fromForm :: Form -> Either Text IncomingMessage fromForm (From form) = case lookupResults of Just ((fromNumber : _), (body : _)) -> Right $ IncomingMessage fromNumber body Just _ -> Left “Found the keys but no values” Nothing -> Left “Didn’t find keys” where lookupResults = do fromNumber <- HashMap.lookup “From” form body <- HashMap.lookup “Body” form return (fromNumber, body) Now that we have this instance, we can finally define our API endpoint! All it needs are the simple path components and the request body. For now, we won’t actually post any response. type TwilioServerAPI = "api" :> "sms" :> ReqBody '[FormUrlEncoded] IncomingMessage :> Post '[JSON] () Writing our Handler Now let’s we want to write a handler for our endpoint. First though, we’ll write a natural transformation so we can write our handler in the monad. Twilio transformToHandler :: Twilio :~> HandlertransformToHandler = NT $ \action -> liftIO $ runTwilio' fetchSid fetchToken action Now we’ll write a simple handler that will echo the user’s message back to them. twilioNum :: TexttwilioNum “+15559879876” smsHandler :: IncomingMessage -> Twilio ()smsHandler msg = do let newMessage = PostMessage (fromNumber msg) twilioNum (body msg) _ <- post newMessage return () And now we wrap up with some of the Servant mechanics to run our server. twilioAPI :: Proxy TwilioServerAPItwilioAPI = Proxy :: Proxy TwilioServerAPI twilioServer :: Server TwilioServerAPItwilioServer = enter transformToHandler smsHandler runServer :: IO ()runServer = do port <- read <$> getEnv “PORT” run port (serve twilioAPI twilioServer) And now if we send a text message to our Twilio number, we’ll see that same message back as a reply! Conclusion In this article, we saw how we could use just a few simple lines of Haskell to send and receive text messages. There was a fair amount of effort required in using the Twilio tools themselves, but most of that is easy once you know where to look! Come back next week and we’ll explore how we can send emails with the API. We’ll see how we can combine text and email for some pretty cool functionality. Mailgun An important thing making these apps easy is knowing the right tools to use! One of the tools we used in this part was the Servant web API library. To learn more about this, be sure to check out our . For more ideas of web libraries to use, download our . Haskell Web Skills Series Production Checklist And if you’ve never written Haskell before, hopefully I’ve convinced you that it IS possible to do some cool things with the language! Download our to get stated! Beginners Checklist
