Quickstart Guide

How about we build a simple app that auto-responds to any incoming text with a gif?

Step 1: Create your app and obtain an access token

First you’ll need to fill out this form with some basic information about your app and we’ll send you the keys you need to handle user authentication. Make sure to add a webhook url like http://yourapp.com/webhook_url in your submission if you want to be able to listen to incoming messages and calls.

Go through the above authorization flow to obtain an access token. Use the scope value: "scope":"messages:write,messages:connect".

The user will be asked to select an active burner to connect their app to. Once the user has selected at least one burner and authorized your app, your app will have permission to listen for new incoming messages and send messages from the burner(s) selected by the the user.

Step 2: Listen for new incoming texts and reply with new messages
  • Look for incoming messages to your webhook url that have a type of inboundText.

Messages sent to the webhook look like:

POST http://yourapp.com/webhook_url

{
  "type": "inboundText", 
  "payload": "Are you there?", 
  "fromNumber": "+12222222222", 
  "toNumber": "+13333333333",
  "userId": "{burner user id}",
  "burnerId": "{burner id}
}
Only burners connected to your app will post to your webhook URL
  • For those messages, store the fromNumber value of the incoming message and the payload.

Now, let’s fetch a gif from giphy. Make a http request to http://api.giphy.com/v1/gifs/random?api_key=dc6zaTOxFJmzC, which will return a random gif from giphy. If you want to get fancy, you could send the payload of the incoming text to giphy to return a random gif with using the body of the message as a search term e.g. http://api.giphy.com/v1/gifs/random?api_key=dc6zaTOxFJmzC&tag={payload_from_text}.

Giphy will return a json payload with a bunch of data. Look for data["image_url"] in the payload returned from giphy.

Step 3: Send back a message

Once you have the image url, we’re ready to send back a message.

  • Create a new message using the messages api:

POST https://api.burnerapp.com/messages

and include the following parameters:

  • burnerId - the id of the burner you want to send the message from. the burner must be connected to the app.
This must be a burnerId that was selected as part of the authorization flow by the user.
  • toNumber - the number you want to send the message to (in this case, the fromNumber from above)
  • text - the body of the text message
  • mediaUrl - a media url you want to send (must be png,jpg,gif,mpg under 5 MB).

That’s it! You’ve successfully enhanced a phone number with just a few lines of code!