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

Send SMS to Contact API

 

This Send SMS API sends a single message to a contact. This API is connected to our Contacts feature, meaning that you can send an existing contactId in your API request and we will send the SMS to that contact. If you pass a phone number, we will send the SMS to the most recently created contact in your organization with that phone number. If no contact exists with that phone number, then we’ll create one.

If you want to send an SMS via API to a phone number and not have us use an existing Contact or create a Contact, then use our Send SMS to Phone Number 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/contact

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 Send SMS to Contact API:

cont

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 “+”.

Note: You cannot send both a phone number and a Contact ID, so include only the “to” parameter if you want to send a phone number in your request.

String (phone number) Yes “639123456789”
contactId

The existing contact Id of your intended recipient.

Note: You cannot send both a phone number and a Contact ID, so include only the “contactId” parameter if you want to send to an existing Contact ID.

Integer (contact Id) Yes 123456
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 (using to parameter):

{
    "orgId": 123,
    "to": "639123456789",
    "from": "engageSPARK",
    "message": "Sample message to you."
    "clientDedup": "message123”
    "clientPushURL": "https://..."
}

Sample JSON (using contactId parameter):

{
    "orgId": 123,
    "contactId": 123456,
    "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 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”
to Displays the phone number of your recipient. String
“639123456789”
contactId Displays the existing contact Id of your recipient. Integer (contact Id) 123456
message Corresponds to the message content in the API request. String “Sample message to you.”

Sample JSON Response (using to parameter):

{
  "error": "",
  "messageId": "SMS20190723T154425-123-0123",
  "estimateParts": 1,
  "estimateMicro": 20000,
  "estimate": "0.02",
  "deliveryDeadline": "2019-07-24T13:49:16.38785625Z",
  "contactId": 654321,
  "to": "639123456789",
  "message": "Sample message to you."
}

Sample JSON Response (using contactId parameter):

{
  "error": "",
  "messageId": "SMS20190723T154425-123-3210",
  "estimateParts": 1,
  "estimateMicro": 20000,
  "estimate": "0.02",
  "deliveryDeadline": "2019-07-24T15:39:41.071667761Z",
  "contactId": 123456,
  "to": "639123456789",
  "message": "Sample message to you."
}

Note: If our system can’t create a contact but the phone number is valid, the system will still send an sms to the phone number but will return a 0 for contactId.

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?