How to send SMS from Dialplan using SMS API

SMS API allows any external software to use Wildix PBX as an SMS Server with the possibility of bulk (mass) SMS sending.

APIs Online Documentation (WMS 6.0X/ 5.0X): use URL https://<pbx-host>/api/v1/doc/ (available only for admin user/ users with admin rights!)

Created: February 2018

Updated: December 2022

Permalink: https://wildix.atlassian.net/wiki/x/BRrOAQ

Requirements:

  • DaySaver/ W01GSM provisioned to your PBX with SIM card

* Before trying to send SMS from Dialplan, make sure SMS can be sent from WEB Collaboration

How to send SMS

Make an HTTP POST/GET request with basic authorization (username/ password of the user who is the SMS sender) to http(s)://<PBX_IP_Address>/api/v1/originate/sms.

In case a GSM gateway to be used for SMS sending is not specified in the command, the message is sent to a randomly chosen GSM gateway configured in the system.

The timeout for mass sending is 5 sec for each SMS / gateway.

The POST/GET required parameters are:

  • message: the body SMS messages, length of no more than 300 characters

    Note: Starting from WMS 6.02.20230306.1:

    • The max. number of characters was increased to 670. 
    • In case SMS sent via CURL contains the following characters, they are replaced with a space:  ' (single quote), “ (double quotes), \ (backslash), / (slash).
  • number: the phone number or several numbers separated by a comma. Example: +391234567890 or +391234567890,+391234567891,+391234567892,...

The POST/GET optional parameters are

  • postpone: date of postponed message delivery. Example: 14/07/2014 15:35
  • gsm: GSM gateway MAC address. Example: 9c7514330001

The response of the service is

Success: {"type":"result","result":"Success"}

Warning: {"type":"warning","reason":"Unable to add a SMS to the queue","result":["111"]}

Error: {"type":"error","reason":"Number should not be empty","result":null}

The "reason" part is the description of the warning/error


To try the service, you can use the curl software and run it from the command line.

Here is the working example:

curl -k -X POST -u 101:sms101api --url "https://127.0.0.1/api/v1/originate/sms"  --data-urlencode 
"number=+39123456789" --data-urlencode "message=This API is awesome, now I can add the sms support to my software" --data-urlencode "gsm=9c7514330001"


To send SMS from Dialplan, apply the following configuration:


  1. Set -> CURLOPT(userpwd) ->  101:sms101api (user credentials) - allows sending API request
  2. Custom application -> Set(message=${CURL(http://127.0.0.1/api/v1/originate/sms, message=the message body&number=%2B39333123456)}); - SMS API is applied  

    Note: You need to specify GSM gateway's MAC address if the option Curl SMS send enabled in WMS Settings -> System -> FAX/ SMS server is activated since it has priority over GSM gateway:

    • Set(message=${CURL(http://127.0.0.1/api/v1/originate/sms, message=the messagebody&number=%2B33611121314&gsm=9c7514330001)});

    By adding MAC address, you can also select a specific GSM gateway if there are > 2 gateways.

Note:

  • "%2B" added to the mobile number is "+" character with URL encoding transformation. The full reference is available on the w3school web site.
  • In case SMS sent via CURL contains the following characters, they are replaced with a space:  ' (single quote), “ (double quotes), \ (backslash), / (slash).

Note: the same way you can send SMS using http SMS server. For this purpose, another PBX with a configured GSM trunk can be used.

How to configure:

  1. Go to WMS Settings -> System -> FAX/SMS server
  2. Check off Curl SMS send enabled option and configure the sending. For example, curl -k -X POST -u user:password --url "http://PBX IP Address/api/v1/originate/sms" --data-urlencode "number={TO_NUMBER}" --data-urlencode "message={MESSAGE}" 
  3. When making SMS API request http(s)://<PBX_IP_Address>/api/v1/originate/sms via Custom application, use IP address of the PBX with a configured GSM trunk