Send SMS to Phone Number API
This Send SMS API sends a single message to a phone number. This API is not connected to our Contacts feature, meaning that when you use this API, we will not create a “Contact” on the engageSPARK platform. We also will not check if a Contact already exists with the phone number, and we will thus not link the message to such a Contact.
If you want to send an SMS via API to an existing Contact (or have us create a Contact), you can use our Send SMS to Contact API.
This SMS API is extremely fast, highly available, and very easy to use. We also offer delightful customer support for all of our APIs via live chat, email, and phone.
Check out our SMS rates by country on our pricing page.
Delivery receipts are available for every message sent via the API.
HTTP Method & Headers
The HTTP method is POST using the URL below:
https://api.engagespark.com/v1/sms/phonenumber
You’ll need to set the following HTTP Headers:
Key | Value |
Authorization | Token {Personal Access Token} |
Content-type | application/json |
Replace {Personal Access Token} with your actual Personal Access Token from your account. Find it in your profile under Account (Avatar icon) > Profile > Info > Personal Access Token (https://app.engagespark.com/account/profile/info). Don’t forget to remove the curly braces { }.
Request Body Definition
Below are the only details we need and you need to provide in order for you to successfully send an SMS using the Phone Number SMS API:
Key | Description | Data Type | Required | Example |
orgId | The id of user’s organization. Find it in your organization profile (https://app.engagespark.com/account/organization/info). | Integer | Yes | 123 |
to | The phone number of your intended recipient in international format without the “+”. | String (phone number) | Yes | “639123456789” |
from | The organization’s caller/sender ID or organization’s local phone number (virtual number). Most countries require sender IDs to be pre-registered. If you set an ID here and you receive the message with an ID other than the one you set, you may want to contact us to pre-register one for branding purposes. Click here to know more about sender IDs. | String | Optional, but recommended. Otherwise, it will be sent with the local telco’s random sender like INFOSMS, NXSSMS, Info, etc. | “engageSPARK” |
message | The content of the message to be sent to the recipient. | String | Yes | “Sample message to you.” |
clientDedup | What clientDedup does is it’ll give an error the 2nd time you use the same “clientDedup” value. This serves as message duplicate checker to make sure you don’t accidentally send the same message to the same contact twice. If you don’t give it, or if you leave it empty, then it is ignored. | String | Optional | “message123” |
clientPushURL | If you add the field clientPushURL we’ll do a POST to that URL whenever we update the delivery notification status of the message. | String | Optional | “https://…” |
Sample JSON:
{
"orgId": 123,
"to": "639123456789",
"from": "engageSPARK",
"message": "Sample message to you."
"clientDedup": "message123”
"clientPushURL": "https://..."
}
Response Body Definition
Below are the details that will be returned after every SMS API request:
Key | Description | Data Type | Example |
error | Shows an error message if an error occurs. Empty if no error. | String |
“invalid ‘to’ number”
|
messageId | The message ID. | String |
“SMS20190723T154425-123-0123″
|
estimateParts | The number of SMS body parts calculated in the message content based on the character limitation. | Integer | 1 |
estimateMicro | Shows the cost estimate of the message. Divide by 1,000,000 to get the $ (USD) equivalent. | Integer | 20000 |
estimate | Shows the estimated cost of the message in $ (USD). | String | “0.02” |
deliveryDeadline | Shows the date and time until when we will retry to deliver the message in cases of network errors. | JSON time |
“2019-07-24T15:39:41.071667761Z”
|
contactId | Displays the existing contact Id of your recipient. For this API, this will always return 0. | Integer (contact Id) | 0 |
to | Displays the phone number of your recipient. | String (phone number) | “639123456789” |
message | Corresponds to the message content in the API request. | String | “Sample message to you.” |
Sample JSON Response:
{
"error": "",
"messageId": "SMS20190723T154425-123-0123",
"estimateParts": 1,
"estimateMicro": 20000,
"estimate": "0.02",
"deliveryDeadline": "2019-07-24T15:39:41.071667761Z",
"contactId": 0,
"to": "639123456789",
"message": "Sample message to you."
}
Note: contactId will always return a 0 for phone number SMS API.
List of Possible HTTP Status Codes
Success:
200 – everything’s fine.
Failed:
400 – there’s something wrong with the request. Please see the error field in the response body.
401 – authentication problems.
402 – not enough funds in the organization/account.
500 – engageSPARK internal service error.
Note: The API’s response structure will always be the same.
For the Philippines, telcos have a 5 sms per mobile number per minute (5 sms/number/minute) capping rule. If you are sending more than 5 sms to a single number within a minute, some messages may not get through and will be lost.
The SMS API automatically re-tries failed messages as often as possible within 24 hours by default. To know up to when we’ll keep retrying your message, you can refer to the deliveryDeadline of your POST request.
Phone Number Formats
Phone numbers in the API need to have an international dialing code.
For example, for a number from the Philippines (with the dialing code 63), 639123456789 would be correct, whereas 9123456789 would be missing the dialing code. If you are not sure about the dialing code of the country you want to send calls or SMS to, check this Wikipedia article on dialing codes.
Have questions or need a little extra help?