ChatGPT & AI: We’re incorporating AI into engageSPARK.

Let's Talk

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.

Related Pages

Have questions or need a little extra help?