Back to developer portal

Burner Developer Documentation

Burner currently allows users to create outgoing and incoming webhooks for each line.  You can edit the developer settings for your Burners by enabling the Developer Connection either via the developer console or via your Burner's settings page.

Outgoing Webhooks

Setting an outgoing webhook in Burner

You can have Burner post data to an outgoing webhook when the a number receives a text message. To create an outgoing webhook for your Burner, you first need to enable the developer connection through the developer console.

  • Select a Burner that you want to create a webhook for and tap "enable."
  • In the Developer Connection section, find the outgoing webhook field and type in the url you want burner to send data to.

Assuming you configured https://mysite.com/my-powerful-burner-events as your url, burner will send the following JSON body whenever the connected burner receives a text message:

{      
  "type": "inboundText", 
  "payload": "Are you there?", 
  "fromNumber": "+12222222222", 
  "toNumber": "+13333333333",
  "userId": "{burner user id}",
  "burnerId": "{burner id}
}

In the above payload, type is one of either inboundText, inboundMedia or voiceMail.

The corresponding payload will either be the inbound text message, or a full media url containing either an image or an audio file.

The toNumber in this case is always the burner number.

The request to the outgoing webhook url would look like

POST https://mysite.com/my-powerful-burner-events -d '{ "type": "inboundText", "payload": "Are you there?", "fromNumber":"+12222222222", "toNumber": "+13333333333", "userId": "d42b8365-f5ab-4b82-96c5-ce30728b57d0", "burnerId": "c0e9fd34-792d-4c98-940b-bdd4851b5514" }'

Incoming Webhooks

Confuguring an incoming webhook

Incoming webhooks can be created for any Burner. Incoming webhooks allow developers to send text messages via the connected Burner simply by hitting the webhook url with some basic parameters.

To create an incoming webhook for your Burner, you first need to enable the developer connection through the developer console.

1) Select a Burner that you want to create a webhook for and tap "enable" or "edit" if already enabled.
2) Find the incoming webhook section and tap "create."

An incoming webhook url will be generated for you in the format:

https://api.burnerapp.com/webhooks/burnerId/{burnerId}?token={token}

Where burnerId is the id of the burner you are setting up the webhook for and token is a unique token that authorizes you to make requests to the url.

  • The token can be regenerated any time by clicking the regenerate button below the webhook url.
  • The incoming webhook can be deleted at any time by clicking the delete button below the webhook url or by disconnecting the developer connection on the burner.

Sending messages

Once your incoming webhook is configured, you can send text messages from your Burner simply by hitting the webhook url with a JSON payload as the body.

Our message is defined in JSON as:

{
  "intent": "message",
  "data": 
  {
    "toNumber": "+15555555555",
    "text": "Hello from my Burner"
  }
}

The intent is set to message. A second field, data requires a toNumber and the text text you want to send to the given number. We will try and parse the phone number if it is not in e164 format, and will return an error if we cannot recognize the number.

You can try this out using curl.

curl -X POST -H 'Content-type: application/json' --data '{"intent":"message", "data": {"toNumber":"+15555555555", "text":"Hello from Burner"}}' https://api.burnerapp.com/webhooks/burner/521c4366-35de-453a-ab56-536cc47281fb?token=3867e4bb-2373-4ddb-97a3-cc06b67a49ac

Rate limits

You will be able to send up to 5 messages per minute to the same number before being throttled. If there is an incoming message to the connected burner, from that number, that rate limit will be cleared.

There will also be an additional rate limit of 30 messages/minute.

Responses

We will respond to the webhook url with either a success or failure JSON message.

200 OK

{
  "success": true
}
400 Bad Request

{
  "success": false,
  "error": {error reason}
}
403 Forbidden

{
  "success": false,
  "error": {error reason}
}
404 Not found

{
  "success": false,
  "error": {error reason}
}

Possible error reasons:

  • JSON body must contain an intent
  • JSON body must contain data
  • JSON data field must contain a toNumber and text to send
  • Provided toNumber phone number cannot be parsed
  • Rate limit exceeded
  • URL is invalid
  • URL doesn't exist