RegisterCallback

Registers a URL where an account will receive asynchronous responses and other messages from an M2M Platform callback service. The messages will be SOAP HTTP request messages. You are responsible for creating and running a listening process on your server at that URL to receive and parse the messages.

NOTE: Registering your callback listening services is usually something that is done once, when your services are up and running. Instead of writing code to do this, you may want to use use the Callback Registration function in UWS Explorer.

Request Parameters

Parameter Type Description
AccountName
required
string The name of the billing account for which you want to receive callback messages. An account name is usually numeric, and must include any leading zeros.
ServiceName
required
string The type of callback messages that you want to receive. Set this to one of the following values:
CarrierService
Asynchronous responses from all Carrier Service APIs: ChangeDeviceCostCenter, ChangeDeviceCustomFields, ChangeDeviceIdentifier, Change4GDeviceIdentifer, ChangeDeviceServicePlan, ChangeDeviceState, and MoveDevice.
DevicePRLInformation
Callback messages containing current device PRL values, in response to GetDevicePRLInformation requests.
DeviceService
Callback messages from Device Service CheckDeviceAvailability API.
DeviceSuspensionStatus
Callback messages containing information about suspended devices, in response to GetDeviceSuspensionStatus requests.
DeviceUsage
Callback messages from Device Service APIs GetAggregateDeviceUsage and GetRatedDeviceUsage.
EnhancedConnectivityService
Receive callback messages from the SendSmsMessage API in the Enhanced Connectivity Service, and also receive SMS messages from devices that can send them to your application.
ExternalProvisioningChanges
Receive callback messages when provisioning changes are made outside of the WNS APIs, such as when a user performs one of the following provisioning actions from an interactive Verizon system:
  • Activate
  • Deactivate
  • Suspend
  • Resume
  • Change ESN
  • Change MEID
  • Change MDN

PromoChanges
Receive unsolicited callbacks for changes to promotional codes. A PromoChange callback message will be sent shortly after the end of a device's billing cycle if a promotional package was removed during the billing cycle.
ResumeTrackingNotification
Receive unsolicited callback messages to notify you about devices that will automatically return to active status. The M2M Platform will send a callback message 7 days before service for a suspended device will auto-resume.
SMSDeliveryConfirmation
Indicates that an SMS Message sent through the SendSmsMessage API was received and acknowledged by the device.
Url 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 M2M data centers. If your service is running on HTTPS, you should use a one-way authentication certificate with a white-listed IP address. In most cases, you should register each service type to a unique a URL address.

NOTE: Allowed port numbers for new callback registrations are 80, 443, 9001-9006 and 50551-50559.

Username
optional
string The user name that the M2M Platform should return in the callback messages. Use the user name to authenticate callback messages. If you are handling multiple accounts and you want them to use the same callback address, you can use this credential to identify the account that a particular message is associated with. Pass an empty element if you don't want to authorize callback messages for this account and service type.
Password
optional
string The password that the M2M Platform should return in the callback messages. Use the password to authenticate callback messages. Pass an empty element if you don't want to authenticate callback messages for this account and service type.

Response Parameters

Parameter Type Description
AccountName string The account for which callback messages will be sent.
ServiceName string The name of the callback service, which identifies the type and format of messages that will be sent to the registered URL.

Example SOAP Request

<soapenv:Envelope
<soapenv:Envelope
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
  xmlns:v2="http://nphase.com/unifiedwebservice/v2" 
  xmlns:nph="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.CallbackRegistrationService">
  <soapenv:Header>
    <v2:token>''current_session_token''</v2:token>
  </soapenv:Header>
  <soapenv:Body>
    <v2:RegisterCallback>
      <v2:Input>
        <nph:AccountName>account_name</nph:AccountName>
        <nph:ServiceName>DeviceUsage</nph:ServiceName>
        <nph:Url>http://10.120.102.183:50559/Callback/API/CallbackService.asmx</nph:Url>
        <nph:Username></nph:Username>
        <nph:Password></nph:Password>
      </v2:Input>
    </v2:RegisterCallback>
  </soapenv:Body>
</soapenv:Envelope>

Example SOAP Response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <RegisterCallbackResponse xmlns="http://nphase.com/unifiedwebservice/v2">
      <Output xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:a="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.CallbackRegistrationService">
        <a:AccountName>account_name</a:AccountName>
        <a:ServiceName>CarrierService</a:ServiceName>
      </Output>
    </RegisterCallbackResponse>
  </s:Body>
</s:Envelope>

Request Schema Diagram

Response Schema Diagram