Set a Callback URL for Your Phone Number

Lets you assign a callback URL to a specific long code or toll-free phone number in your account for POST notifications of inbound SMS or MMS messages, or delivery receipts (DLRs) of messages you have sent from that number.

Callback Service

Make sure to assign a publicly accessible URL for your messaging callback service.

Endpoint

POST /numbers/{id}/relationships/{callback_type}

Request Parameters

Path Parameters

id
integer required
The phone number to be associated with the messaging callback URL.
callback_type
string required
Callback type to be associated with the specified phone number. Allowed values are:
- sms_callback
  Called for inbound SMS messages (see Receive an SMS).
- mms_callback
  Called for inbound MMS messages (see Receive an MMS).
- sms_dlr_callback
  Called for SMS Delivery Receipts (see Receive a DLR).
- mms_dlr_callback
  Called for inbound MMS Delivery Receipts (see Receive a DLR).

Body Parameter

callback_url
string required
The callback URL to be assigned to your longcode or toll-free number. For example, if you specify 18331231234 and sms_dlr_callback as path parameters, the value that you set this field to will be the URL associated with the outbound SMS DLR callback service for 18331231234. To learn more about Flowroute's DLR callback service, see Receive a DLR.

Response Format

On success, the HTTP status code in the response header is 204 No Content which means that the server successfully processed the request and is not returning any content. On error, the header status code is an error code and the response body contains an array of error objects.

JSON API
cURL

Please make sure to use neutral (vertical) quotes in your request. Smart quotes are known to cause errors.

Example Request

POST /v2/numbers/12014845220/relationships/sms_dlr_callback HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "attributes": {
      "callback_url": "https://requestbin.fullcontact.com/tjji7itj"
    }
  }
}

Please make sure to use neutral (vertical) quotes in your request. Smart quotes are known to cause errors.

Example Request


curl https://api.flowroute.com/v2/numbers/12014845220/relationships/dlr_callback \
-H "Content-Type: application/vnd.api+json" -X POST \
-d '{"data": {"attributes": {"callback_url": "https://requestbin.fullcontact.com/tjji7itj"}}}' \
-u accessKey:secretKey

Example Response

204 No Content

401 Unauthorized

{
  "errors": 
  [
    {
      "status": 401, 
      "detail": "Authentication failed.", 
      "title": "Unauthorized"
    }
  ]
}

405 Method Not Allowed

Returned when specifying an invalid callback type.

{  "errors": 
  [
     {
      "detail": "The method is not allowed for the requested URL.",
      "id": "e806c574-53e6-4f53-9430-f90a70100bb2",
      "status": 405,
      "title": "Method Not Allowed"
    }    
  ]
}

numbers v2

Purchasable Phone Numbers

Phone Numbers

Inbound Routes

E911 Addresses

CNAM Storage

MESSAGING CALLBACK SERVICES

Errors

Set a Callback URL for Your Phone Number

Callback Service

Endpoint

Request Parameters

Path Parameters

id

callback_type

Body Parameter

callback_url

Response Format

Example Request

Example Request

Example Response

204 No Content

401 Unauthorized

405 Method Not Allowed