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

Subscription API

 

When you want to subscribe more contacts to any of your running campaigns on the go, what you need is a Subscription API. This allows you to not only subscribe contacts, you can also set when exactly you want the contact to be subscribed.

HTTP Method & Headers

The HTTP Method is POST using the URL below:

https://api.engagespark.com/v1/organizations/{orgid}/engagements/{campaignid}/subscribe

Replace {orgid} with your own organization ID and {campaignid} with the ID of the campaign where you want the contact or phone number to be subscribed. You can find the {orgid} in https://app.engagespark.com/account/organization/info and the {campaignid} in the actions menu dropdown to the left side of your campaign name.

Don’t forget to remove the curly braces { }. 

 

campaigns_engageSPARK

 

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). And again, don’t forget to remove the curly braces { }. 

Request Body Definition

The contact parameters are the key-value pair you need to provide in your API POST request body. You can decide whether to POST using a contactId, a fullPhoneNumber in international format, or a phoneNumber in local or national format. 

Note: The same contact cannot be re-subscribed to the same campaign while it is still in the flow or has not yet completed. 

Click on the links below to learn more about the different Contact Parameters that you can choose from to successfully subscribe a contact or phone number to a running campaign:

Contact Parameter: contactId >>

Contact Parameter: fullPhoneNumber >>

Contact Parameter: phoneNumber >>

Response Body Definition 

Below is the only detail that will be returned after every Subscription API request: 

Key Description Data Type Example
runId

It is a unique subscription ID that is automatically assigned to a contact.

The same contact cannot be re-subscribed to the same campaign while it is still in the flow or has not yet completed.

You can re-subscribe a contact as soon as it finishes the flow or has received all the messages in the campaign. When you do, a new runId will be assigned to that contact.

Integer 1


Example JSON Response:

{
  "runId": 1
}

Delay Parameter – Optional

When you use the Subscription API to subscribe contacts to a running campaign in your account, the contact immediately gets subscribed.

However, if you want to set a time delay of when you want the contact to be subscribed to the campaign, you can add a delay parameter in your API POST request.

Key Description Data Type Example
unit You can set this to “second” | “minute” | “hour” | “day” | “week”. Click here for more information on the delay scheduling. String “second”
value The value of unit you want your delay to be. Click here for more information on the delay scheduling. Integer 60
dayOfWeek This is only relevant for “week” unit. It represents the day of when subscription happens. String Monday
time This is only valid if “unit” is “day” or “week”. It represents the next time when subscription happens. If “time” is set, “timezone” needs to be set as well. Timestring in 24h format ’13:00′ or ’23:59′
timezone You can set this to let the system know which timezone you want it to follow when scheduling the subscription. You can refer to the correct timezone formatting here. String “America/New_York” or “Asia/Manila”


Example JSON using fullPhoneNumber with delay parameters:

1. Contact is subscribed in 60 seconds

Request Type: POST

Headers:

“Authorization”: “Token {Personal Access Token}”

“Content-Type”: “application/json”

URL: https://api.engagespark.com/v1/organizations/{orgid}/engagements/{campaignid}/subscribe

Body parameter:

{
"fullPhoneNumber": "639123456789"
"delay": {
        "unit": "second",
        "value": 60
        }
}

2. Contact is subscribed at 13:00 one day later

Request Type: POST

Headers:

“Authorization”: “Token {Personal Access Token}”

“Content-Type”: “application/json”

URL: https://api.engagespark.com/v1/organizations/{orgid}/engagements/{campaignid}/subscribe

Body parameter:

{
"contactId": "123"
"delay": {
        "unit": "day",
        "value": 1,
        "time": "13:00",
        "timezone": "Asia/Manila"
        }
}

3. Contact is subscribed next week Monday at 09:00:

Request Type: POST

Headers:

“Authorization”: “Token {Personal Access Token}”

“Content-Type”: “application/json”

URL: https://api.engagespark.com/v1/organizations/{orgid}/engagements/{campaignid}/subscribe

Body parameter:

{
"phoneNumber": "09123456789",
"phoneNumberCountry": "PH",
"delay": {
        "unit": "week",
        "value": 1,
        "dayOfWeek": "Monday",
        "time": "09:00",
        "timezone": "Asia/Manila"
        }
} 

 

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.

Retries: 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.

Testing: In many countries, mobile network operators limit the number of SMS you can send to a single number per minute often 5 sms/number/minute). 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.

Phone Number Formats

If you use the fullPhoneNumber contact parameter in the API it needs 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?