The following describes how messages are transmitted using Flowroute and received at your callback URL. Flowroute transmits messages to your phone number using HTTP to a callback URL you specify. Inbound messages are formatted using the SMS format described here.


Callback URLs

The callback URL must be a web resource with a public IP address configured to handle JSON, as shown in the example below.

1. Set the callback URL

Set a callback URL in the SMS Call-Back field in the Preferences > API Control section of the Flowroute portal:

2. Receive an inbound message

When an SMS is sent to a Flowroute phone number, Flowroute will send a POST HTTP request to your callback URL containing the following information:

Key Value
to The Flowroute phone number that received the message. This must be in E.164 format, which is an 11-digit 1NPANXXXXXX-formatted number in North America.
from The phone number from which the message was sent. This must be in E. 164 format, which is an 11-digit 1NPANXXXXXX-formatted number in North America.
body The body content of the message. Messages are encoded in UTF-8.
id The Message Detail Record (MDR) identifier of the received message.

Example of an inbound message request:

POST /runpost HTTP/1.1 Content-Length: 72 
Content-Type: application/json 
Accept-Encoding: gzip
  "to": "12066418000",
  "body": "Hello there from Flowroute!",
  "from": "18553569768",
  "id": "mdr1-febb 118b.9b034338adfo662a3C02fd88"

Message Auto-Concatenation

Auto-concatenation rules apply to any inbound message. See Message Length & Concatenation for more information.

3. Respond to the HTTP request

When you receive an inbound message, you must respond with a 200 OK response. If you do not send a 200 OK, an attempt is made to resend the message a total of four (4) times at 30-second intervals.

Even if you don’t respond to the request, you will still be billed for that message. However, you can still retrieve the message by looking up the MDR date. See Look Up a Set of Messages for more information.

Code Description
200 Send back a 200 OK to acknowledge the receipt of a message. Anything else (or no response) will trigger a retransmission of the message to your callback URL.

Protect your callback URL

You can protect your callback URL by only accepting inbound connections from Flowroute’s API endpoints. The IP addresses are: