SMS using the API

How to send and receive SMS messages with the GoFax REST API

How to send SMS

To send a SMS, submit a PUT request to /v1.0/SMS, with the below example JSON payload.

{// SMS message object
  "To": [ //Array of SMS recipients
    "61412341234", // 1 or more valid E.164 mobile number 
    "61412341234" 
  ],
  "From": "Test Sender" // SMS Sender ID - As shown on destination handset
  "Body": "Hello World", // Message body 160 chars = 1 message part
}

If your SMS was successfully submitted, you will see a response similar to below:

{
    "Success": true,
    "Message": "SMS Submitted",
    "ValidationErrors": null,
    "Response": 52336014 // Message ID for your SMS job. Store this for later
}

See our Swagger UI for all available SMS parameters.

How to get SMS status

SMS messages may not be delivered instantaneously for various reasons including but not limited to, availability of remote handset and the carrier level routing. 

We highly recommend using webhooks in an event based architecture to track the status of an SMS. Please see our Using Webhooks guide to assist you. 

Alternatively, you can query the status of a SMS job using the message ID (see above SMS submission response) in the GET /v1.0/SMS/{smsId} endpoint.

💡"{smsId}" = message ID

Example response: 

{
    "Success": true, 
    "Message": null,
    "ValidationErrors": null,
    "Response": {
        "MessageID": 52356593,
        "Sender": "Test Sender", //Your SMS sender ID after data cleanup (removing invalid chars)
        "Message": "Hello World", //The contents of the message
        "Issued": "2023-04-19T10:10:45.237", //Datetime of submission
        "IssuedUtc": "2023-04-19T00:10:45.237",
        "FromNumber": "Test Sender", //Your SMS sender ID before data cleanup (as originally submitted)
        "ToNumber": "61412341234", // The recipient of your SMS
        "Status": "Sent – Submitted to carrier for delivery",
        "Charge": 0.80, // 0.8 Send Credit charge for 1 message part (160 characters)
        "Sent": "2023-04-19T10:10:45.983", //Datetime when message was submitted to GoFax SMS carriers.
        "SentUtc": "2023-04-19T00:10:45.983",
        "Complete": "2023-04-19T10:10:56.047", //Datetime when message reached a final status
        "CompleteUtc": "2023-04-19T00:10:56.043",
    }
} 

Get SMS Replies

You can retrieve an SMS reply using a message ID of the originally sent message by sending a GET request to /v1.0/SMS/Reply/{smsId} where "{smsId}" is the previously gather message ID (see above). 

The response will include the first SMS reply for that particular message ID.

{
    "Success": true,
    "Message": null,
    "ValidationErrors": null,
    "Response": {
        "ID": 52358093,
        "Message": "Yep it's working, this is my reply!", // The contents of the reply.
        "RecipientID": 52378921,
        "Charge": 0.00,
        "Received": "2023-04-19T10:34:03.76", //Datetime the reply was received.
        "RecipientNumber": "61412341234", //Recipient who replied
        "IssuedUtc": "2023-04-19T00:34:03.76",
    }
}

Use the GET /v1.0/SMS/Replies and  GET /v1.0/SMS/Replies/{count} endpoints to retrieve a list of replies, where "{count}" is the number of SMS replies you want to retrieve.

At this time, there is no webhook for incoming SMS replies, they must be queried directly on the API at an interval.

For further details regarding any of the above REST API endpoints, please refer to our API reference (Swagger UI).