Receive SMS API Callbacks

Receive SMS API callbacks

Contents

Overview

The ThingSpace SMS API uses asynchronous callbacks (webhooks) to send messages to your application. Asynchronous callbacks are essentially a reversal of the client-server arrangement that you use for sending API requests.

  • When your application sends API requests, your application is the client and ThingSpace is the server offering the API resources. Your application sends GET, POST, etc. requests to our server at the URL that we’ve provided.

  • For callbacks, ThingSpace will be the client, and will send POST requests to your server. You need to create a callback listener application to accept, process, and respond to those requests. You also need to tell ThingSpace the type of information that you want to receive and where to send it, which you do with a POST /callbacks request.

Subscribing to callback messages

To receive callback messages, you will need to create and deploy a web service that can validate and process REST messages that conform to the SMS Callback JSON schema. You then need to register the URL of your web service through the SMS API so that it knows where to send the callback messages.

You can run multiple callback listening services on a single server, but your application will be more robust if you use a separate port for each callbackType.

You only need to register once for each callbackType that you want to receive. You do not need to subscribe to all messages – only to those that are applicable to your needs.

NOTE: To test your callback listening services in a non-production environment, you must have an external URL for the computer or server that is hosting the web services. ThingSpace cannot send callback messages to a system that does not have a URL.

Callback security

When you register to receive any type of callback messages, you can specify a username and/or password that you want ThingSpace to use with each request. It will send the username and password in the request header as basic access authentication.

Note that basic authentication does not provide confidentiality; the credentials are not encrypted or hashed in any way. For increased security, you should install a one-way certificate and enable HTTPS. You must use a certificate from a third-party certificate service such as Verizon Terremark; a self-signed certificate will not work. ThingSpace will check the validity of the certificate at the start of every session.

Callback JSON schema and examples

SMS_MobileOriginatedMessage

Schema

{
  "type":"object",
  "properties":{
    "transactionID":{
      "description":"",
      "type":"string"
    },
    "sender":{
      "description":"The sending device's phone number",
      "type":"string"
    },
    "recipient":{
      "description":"The long code of your application",
      "type":"string"
    },
    "content":{
      "description":"The SMS message body",
      "type":"string"
    }
  }  
}

Example

{
  "transactionID": "AAA-123214123123",
  "sender": "6177807222",
  "recipient": "110000013103",
  "content": "This is content sent from a device"
}

SMS_DeliveryReport

Schema

{
  "type":"object",
  "properties":{
    "transactionID":{
      "description":"The transactionID from the POST /sms request.",
      "type":"string"
    },
    "sender":{
      "description":"The long code of your application",
      "type":"string"
    },
    "recipient":{
      "description":"The receiving device's phone number",
      "type":"string"
    },
    "date":{
      "description":"Date and time of status, in Unix timestamp format (milliseconds since epoch)",
      "type":"string"
    },
    "smsStatus":{
      "description":"The delivery status of the message.",
      "type":"string"
    },
    "statusText":{
      "description":"Details of the status.",
      "type":"string"
    }
  }  
}

Example

{
  "transactionID": "AAA-123214123123",
  "sender": "110000013103",
  "recipient": "6177807222",
  "date": "1473803788123",
  "smsStatus": "Delivered",
  "statusText": "Delivered"
}

OptIn

Schema

{
  "type":"object",
  "properties":{
    "transactionID":{
      "description":"",
      "type":"string"
    },
    "code":{
      "description":"The long code of your application",
      "type":"string"
    },
    "recipient":{
      "description":"The device's mobile number",
      "type":"string"
    },
    "source":{
      "description":"Source of the opt in (SMS or MO)",
      "type":"string"
    },
    "message":{
      "description":"User's message to opt in, usually 'Start'",
      "type":"string"
    },
    "type":{
      "description":"The request type (OptIn)",
      "type":"string"
    }
  }  
}

Example

{
  "transactionID": "AAA-123214123123",
  "code": "110000013103",
  "recipient": "6177807222",
  "source": "SMS",
  "message": "Start",
  "type": "OptIn"
}

OptOut

Schema

{
  "type":"object",
  "properties":{
    "transactionID":{
      "description":"",
      "type":"string"
    },
    "code":{
      "description":"The long code of your application",
      "type":"string"
    },
    "recipient":{
      "description":"The device's mobile number",
      "type":"string"
    },
    "source":{
      "description":"Source of the opt out (SMS or MO)",
      "type":"string"
    },
    "message":{
      "description":"User's message to opt in, usually 'Stop'",
      "type":"string"
    },
    "type":{
      "description":"The request type (OptOut)",
      "type":"string"
    }
  }  
}

Example

{
  "transactionID": "AAA-123214123123",
  "code": "110000013103",
  "recipient": "6177807222",
  "source": "SMS",
  "message": "Stop",
  "type":"OptOut"
}