Register A Callback Listener

Register a URL to receive callback messages: POST /callbacks

Registers a URL at which an account will receive delivery reports and mobile-originated messages. The messages will be REST messages using HTTP POST. You are responsible for creating and running a listening process on your server at that URL to receive and parse the messages. See Receive SMS API Callbacks for the callback schema.

Contents

See also:
Receive SMS API Callbacks
List Callback Listeners
Deregister a Callback Listener

Request Components

HTTP Request

POST https://thingspace.verizon.com/api/messaging/v1/callbacks

Resource Path and Query Parameters

None.

Header Parameters

The request header must contain a current ThingSpace authorization bearer token.

Parameter Name Data Type Description
Authorization
required
string HTTP Authorization request header.

Request Body

The body contains the URL of the callback listener, and the specifics of the callback information that is being requested.

Parameter Name Data Type Description
callbackType
required
string The type of callback messages that you want to receive at the specified URL. Set this to one of the following values:
  • SMS_DeliveryReport
    Reports of message delivery to devices, in response to POST /query/deliveryStatus requests.
  • SMS_MobileOriginatedMessage
    Messages sent by devices to the code specified in code.
  • OptIn
    Notifications when devices opt-in to the service identified by code.
  • OptOut
    Notifications when devices want to stop receiving messages provided by code.
  • Default
    URL to use for any callbackTypes that have not been registered individually. For example, if you register a Default URL but don’t register a URL for the OptIn and OptOut callback types, those messages will be sent to the Default URL. You can have all callbacks go to this one URL, if your callback listener is prepared to receive them. This option is useful for testing, but can also be used for production.
code
required
string The long code for the service for which you want to receive notifications and mobile-originated messages.
url
required
string The address on your server where you have enabled a listening service for callback messages. Specify a URL that is reachable from the Verizon data centers. If your service is running on HTTPS, you should use a one-way authentication certificate with a white-listed IP address.
username
optional
string The user name that the ThingSpace Platform should use in a Basic Authentication request header for callback messages.
Pass an empty element if you don’t want to authorize callback messages for this code and callback type.
password
optional
string The password that the ThingSpace Platform should use in a Basic Authentication request header for callback messages. Pass an empty element if you don’t want to authenticate callback messages for this code and callback type.

Example Request Body

{
  "callbackType": "OptIn",
  "code": "9038644951",
  "url": "http://10.120.102.183:50559/userRegistration.asmx",
  "username": "Zaffod",
  "password": "A14:93r6k"
}

Success Responses

Status 200

Parameter Name Data Type Description
success boolean True for status 200 response.

Example Success Response

{
  "success": true
}

Failure Responses

Status 400

All error messages are returned in this format:

{
  "error": "The type of error, such as INVALID_REQUEST.",
  "error_description": "Additional error information.",
  "error_url": "Optional URI with more information about the error."
}

The error_url field will not be present if there is no URI for more information.

Error codes and messages are listed on the Status Codes page, along with explanations and suggestions for corrective actions.

Try It Out!