URL Networks

Receive SMS via Web Hook

You are here: Help Hosted PBX Receive SMS via Web Hook


If you have your own custom application and would like to receive incoming messages via a webhook this guide will explain the process.

Configuring the Endpoint

  1. Login to your account
  2. Manage your PBX service
  3. Select Numbers 
  4. Click SMS (this will only appear if you have an SMS capable number available)
  5. Enter the following:
    1.  Web Hook URL - The address you want messages to be sent to e.g. http://yourwebserver.com/sms/test
    2. Web Hook Fallback Email - The email address messages should be sent to if a HTTP 200 is not received.


Receive the HTTP Data

Once you have configured the HTTP endpoint you will need to write your code to look at the following standard HTTP Post variables:

ParameterDescription
service_id
The service id the message was received by
from
The name or number that sent the message
sms_number
The number the message was sent to, this will be your number
body
The SMS text message
message_id
Unique message UUID (see https://en.wikipedia.org/wiki/Universally_unique_identifier) for more information about UUID
timestamp
The EPOCH timestamp the message was received
webhook_url
Endpoint the message was sent to
webhook_url_fallback
The destination to send messages to if there is an error

To confirm you have received the message it is important your web server responds with a HTTP status code 200.  Any other code is assumed to be a failure and will keep trying.  If unsuccessful after 10 attempts then it the message will be delivered via email.

Testing

You can use the following command to test from the command line whilst developing your application. 

curl -X POST 'https://youendpoint.com/sms/test' --data "service_id=YOUR_SERVICE_ID&from=YOUR_FROM_NUMBER&sms_number=YOUR_SMS_NUMBER&body=Test%20Message&message_id=297abf7f-99d9-4b7d-9c46-1d7c13687b11&timestamp=1576391654&webhook_url=https://youendpoint.com/sms/test&webhook_url_fallback=you@email.com"