¶ SMS Connector
¶ Introduction
One of the major new additions in version 7.2 is the introduction of the SMS Connector API, which is a flexible and standardized interface used for sending and receiving SMS and MMS messages on PBXware using custom SMS Trunks.
This feature allows our customers to develop middleware applications and connect PBXware's SMS Service with SMS Providers even if they are currently not supported in PBXware.
With a middleware application operational, further PBXware configuration is straightforward.
To create a custom trunk, login to your PBXware GUI and navigate to:
Multi-Tenant Edition:
Master Tenant -> SMS -> Trunks and click add SMS Trunk.
CC/Business Edition:
SMS -> Trunks and click add SMS Trunk.
Enter the Name of your new SMS trunk (i.e. Custom SMS Provider).
In the Provider field, from the drop-down list, select “Custom”.
The Webhook URL field has to be populated with the address SMS/MMS messages sent via gloCOM will be sent to.
With a Custom provider selected, a new field, Auth Token, will appear, allowing you to enter the token used for authentication with the remote application.
The Description field allows you to provide relevant information about this trunk that could be useful to you or other PBXware administrators.
Once all the fields are correctly populated, click Save to preserve changes and create your new Custom trunk.
Assuming the middleware application you are connecting to works as intended, from this point on the Custom SMS trunks will be used just as any other provider-specific SMS trunk available on PBXware.
These are the fields you will be presented with after you select Custom in the Provider field:
- Enable: Click this toggle button to enable or disable this SMS trunk.
- Name: Displays a Trunk's name.
- Provider: Displays the provider selected for this Trunk. (i.e. Custom).
NOTE: For the Custom option to be available when creating a new SMS trunk, the SMS Connector feature has to be enabled in your PBXware license.
- Webhook URL: The address of the middleware application used for interfacing with the custom trunk provider all SMS/MMS messages will be sent to.
- Auth Token: A token used for authentication with the middleware application. Enter the existing or generate a new token by pressing the icon at the far right of the field.
¶ How it works?
¶ Message Send
PBXware's SMS Service will send SMS messages to the defined Webhook URL as a POST request.
POST {webhook_url}
Content-Type: application/json
Authorization: Bearer {auth_token}
{
"from": "string", // Sender's phone number
"to": "string", // Recipient's phone number
"text": "string", // Message content
"media_urls": ["string"] // List of URLs for multimedia attachments (MMS)
}
The SMS Gateway listening on the Webhook can then take the information from the JSON body and send a request to any SMS provider.
The SMS Gateway should return a response as a JSON object in the following format:
// case when sending the SMS was successful
{
"status": "success",
"message": ""
}
// case when sending the SMS was unsuccessful
{
"status": "error",
"message": "an error occured while sending the MMS"
// an error message explaining why sending failed
}
NOTE: If the HTTP Response Status Code is not 200, the message will be treated as failed.
¶ Message Receive
PBXware's SMS Service receives SMS messages as a POST request in the following format:
POST /smsservice/connector
Content-Type: application/json
Authorization: Bearer {auth_token}
{
"from": "string", // Sender's phone number
"to": "string", // Recipient's phone number
"text": "string", // Message content
"media_urls": ["string"] // List of URLs for multimedia attachments (MMS)
}
Response statuses:
- 200 OK: SMS received successfully.
- 401 Unauthorized: The authorization header was missing or the Auth Token is invalid.
- 500 Internal server error: More information about the error should be provided in the response.
¶ Examples
¶ Receiving Messages from PBXware's SMS Service
from flask import Flask, request, jsonify
app = Flask(__name__)
def send_message_to_provider(message_data):
# The implementation of this function should be replaced with the actual
# implementation of sending the message_data to another provider
# For example, printing the received message data
print("Message received:", message_data)
return {"status": "success", "message": "Message sent successfully"}
@app.route('/messages', methods=['POST'])
def messages():
try:
# Ensure the request has a JSON content type
if request.headers['Content-Type'] != 'application/json':
return jsonify({"status": "error", "message": "Invalid content type"}), 400
# Parse the JSON data from the request body
message_data = request.get_json()
# Call the function to send the message to the provider
result = send_message_to_provider(message_data)
return jsonify(result)
except Exception as e:
# Handle any exceptions that might occur during processing
return jsonify({"status": "error", "message": str(e)}), 500
if __name__ == '__main__':
# Run the server on localhost:5000
app.run(debug=True)
¶ Sending Messages to PBXware's SMS Service
from flask import Flask, request, jsonify
import requests
app = Flask(__name__)
def parse_provider_request():
try:
# Ensure the request has a JSON content type
if request.headers['Content-Type'] != 'application/json':
raise ValueError("Invalid content type")
# Parse the JSON data from the provider's request body
provider_message_data = request.get_json()
# Create a new JSON in the specified format
formatted_message = {
"from": provider_message_data.get("sender_number", ""),
"to": provider_message_data.get("recipient_number", ""),
"text": provider_message_data.get("message_content", ""),
"media_urls": provider_message_data.get("media_urls", [])
}
return formatted_message
except Exception as e:
raise ValueError(f"Error parsing provider request: {str(e)}")
@app.route('/messages', methods=['POST'])
def messages():
try:
# Parse the provider's request using the function
formatted_message = parse_provider_request()
# Set up the headers for the outgoing request to my.pbxware.com/smsservice/connector
headers = {
'Authorization': 'Bearer YOUR_AUTH_TOKEN', # Replace with your actual Auth Token
'Content-Type': 'application/json'
}
# Send the message to the my.pbxware.com/smsservice/connector endpoint
response = requests.post('https://my.pbxware.com/smsservice/connector', json=formatted_message, headers=headers)
# Check if the request was successful (HTTP status code 2xx)
if response.ok:
return jsonify({"status": "success", "message": "Message sent successfully"})
else:
return jsonify({"status": "error", "message": f"Failed to send message. Error: {response.text}"}), response.status_code
except ValueError as ve:
# Handle parsing errors
return jsonify({"status": "error", "message": str(ve)}), 400
except Exception as e:
# Handle any other exceptions that might occur during processing
return jsonify({"status": "error", "message": str(e)}), 500
if __name__ == '__main__':
# Run the server on localhost:5001
app.run(debug=True, port=5001)