Send Bulk Messages - Campaigns

post

https://connect.routee.net/sms/campaign

Routee allows to send messages to multiple recipients/contacts/groups. This is a paid service. For pricing check here

RESPONSE PARAMETERS

KEY	DESCRIPTION
trackingId	The tracking id used to identify the campaign.
createdAt	The date that this resource was created.
type	The service type of the campaign.
scheduledDate	The time the campaign is scheduled to run.
campaignName	The name of the campaign.
from	The sender of the message.
to	The phone numbers the message is about to be sent to.
body	The message you sent.
state	The state of the campaign.
statuses	Defines the number of SMS per message status. Either, Queued, Sent, Unsent, Failed, Delivered, Undelivered. Check here for more information
smsAnalysis	The data analysis the this SMS.
smsAnalysis.contacts	The details for each contact. The key refers to the id of the contact given in the request.
smsAnalysis.contacts.recipient	The mobile phone that corresponds to the given contact id.
smsAnalysis.contacts.recipientCountry	The country that corresponds to the given contact id.
smsAnalysis.contacts.blacklisted	Indicates if the contact is in the blacklist. If true the contact will be excluded from the request.
smsAnalysis.numberOfRecipients	The total number of recipients.
smsAnalysis.recipientCountries	The country that each mobile belongs to. The key refers to the mobile of the recipients request property
smsAnalysis.recipientsPerCountry	The total recipients per country. The key refers to the country.
smsAnalysis.recipientsPerGroup	For each group the number of recipients that it contains without the blacklisted contacts (in SMS blacklist). The key refers to the group given in the group request property.
smsAnalysis.totalInGroups	The total number of recipients in all given groups excluding the ones already specified (in contacts and recipients request property) as well as the ones that are blacklisted.
smsAnalysis.bodyAnalysis	The analysis for the body of the SMS.
smsAnalysis.bodyAnalysis.characters	The total number of characters of message body.
smsAnalysis.bodyAnalysis.parts	The number of actual SMS that will be sent.
smsAnalysis.bodyAnalysis.transcode	Contains information for the transcoded body of the SMS message. This will be available only if the message can be transcoded.
smsAnalysis.bodyAnalysis.transcode.message	The transcoded message of the original unicode message.
smsAnalysis.bodyAnalysis.transcode.parts	The number of the parts of the transcoded message.
smsAnalysis.bodyAnalysis.unicode	Indicates if the body contains unicode characters.
smsAnalysis.bodyAnalysis.unsupportedGSMCharacters	Which characters caused the message to be considered as unicode.
flash	Indicates if the message is a flash SMS.
respectQuietHours	Indicates if the SMS should respect the quiet hours.
callback	Defines the notification callback information for an individual SMS message
callback.url	The URL that Routee will POST to, each time your message status changes to one of the following: Queued, Failed, Sent, Unsent, Delivered, or Network Error. When Routee POSTs back to your service, a HTTP 200 OK response must be returned. If Routee doesn't receive a 200 OK response, it will try to POST again (up to 5 times)
callback.strategy	When the URL will be called. Two possible values: on every status change (OnChange) or when a final status arrives (OnCompletion)
campaignCallback	Defines the notification callback information for the progress of the SMS campaign.
campaignCallback.url	The URL that Routee will POST to, each time your campaign status changes to one of the following: Scheduled, Queued, Sent, Running, Finished, or Failed. When Routee POSTs back to your service, a HTTP 200 OK response must be returned. If Routee doesn't receive a 200 OK response, it will try to POST again (up to 5 times).
campaignCallback.strategy	When the URL will be called. Two possible values: on every status change (OnChange) or when a final status arrives (OnCompletion).
reminder	Defines the recipients that will receive a test SMS before the actual SMS is sent.
reminder.minutesBefore	The minutes before the scheduled date (that the SMS will be sent) for the test SMS to be sent.
reminder.to	The recipients that will get the test SMS before the campaign will start. Must be a list with valid mobile numbers starting with “ + ” and the country code.
contacts	The contacts in the account selected as recipients.
groups	The groups of contacts in the account selected as recipients.
fallbackValues	Defines the default values in case a contact does not contain any of the selected personalized labels. The key refers to the label name.
ttl	The duration in minutes the delivery of an SMS will be attempted. If the SMS is not delivered within the validity period, then the SMS status will be "Undelivered", with "detailedStatus": "Expired"
errors.code	The code of error
errors.developerMessage	Message of error
errors.property	The numbers of invalid recipients

ERROR CODES

STATUS	CODE	DESCRIPTION
400	400001009	You don't have enough balance to send the campaign.
400	400005000	The sender id is invalid (errorCode: 002), or you haven't specified any recipients (errorCode: 004) or the recipient numbers are not valid mobile numbers (errorCode: 008). Keep in mind that If your recipients (either in "to", "groups" or "contacts" array) contain at least one invalid number, then the bulk send out will not be dispatched. Try to exclude the invalid recipients in order your campaign to be sent.
409	409009003	Your account already has a campaign with the given name.
400	400009004	Your campaign has no recipients. Your groups might be empty or all contacts might be blacklisted.
404	404002001	A contact id does not exist.

Body Params

contacts

array of strings

The contact ids that the message will be sent to. Contacts have to be uploaded to the system. One of "groups", "to", "contacts" parameters is required.

contacts

groups

array of strings

The groups of contacts in the account selected as recipients. Groups have to be created at the system. One of "groups", "to", "contacts" parameters is required.

groups

array of strings

The phone numbers (array) the message is about to be sent to. Format with a '+' and country code e.g., +306948530920 (E.164 format). Maximum array of number allowed 30k. One of "groups", "to", "contacts" parameters is required.

from

string

required

The sender of the message. This can be a telephone number (numeric string with maximum length 16 characters) or an alphanumeric string (maximum length 11 characters). When you want to use a number, you have to enter it without the '+' before the country code (eg 447123123456).

body

string

required

The message you want to send. Use "\n" to create a new line in your message. Use [~{labelName}] in order to send personalized messages, by using the labels of your contacts.

scheduledDate

date

Defines the scheduled date and time in UTC. (eg YYYY-MM-DDThh:mm:ssTZD where TZD is the time zone designator (Z or +hh:mm or -hh:mm))

campaignName

string

The name of the campaign. If you want to be able to track the whole campaign from Routee web platform use a name. If no name is provided you won’t be able to see the campaign from Routee web platform but you can track all the individual messages. Must be between 2 and 30 characters and contain only latin letters, numbers, spaces and -

flash

boolean

Defaults to false

Indicates if the SMS is a flash SMS. A flash SMS is a type of SMS that appears directly on the main screen without user interaction and is not automatically stored in the inbox. It can be useful in emergencies, such as a fire alarm or cases of confidentiality, as in delivering one-time passwords. Default value false

respectQuietHours

boolean

Defaults to false

Indicates if the SMS should respect the quiet hours. Quiet Hours are set by default to 23.00 - 08.00 and 14.00-17.00 destination local time. Please note that not all countries are supported with this feature due to multiple time zones within the country. Default value false

campaignCallback

object

Defines the notification callback information for the progress of the SMS campaign. Check here for the payload information

callback

object

Defines the notification callback information for an individual message progress of the SMS campaign. Check here for the payload information

reminder

object

Defines the recipients that will receive a test SMS before the actual SMS campaign is sent.

fallbackValues

string

Defines the default values when the SMS has labels, in case a contact does not contain any of these labels.

ttl

int32

Defaults to 4320

The duration in minutes the delivery of an SMS will be attempted. Must be between 1-4320. By default Routee will attempt delivery for 72 hours. If the SMS is not delivered within the validity period, then the SMS status will be "Undelivered", with "detailedStatus": "Expired"

allowInvalid

boolean

Defaults to false

Allow invalid recipients. By setting 'allowInvalid' to true, the API will not return the invalid numbers and will sent the messages to the valid ones only

urlShortener

object

[OPTIONAL] If present, each link that exist in message body will be replaced by a Shortened URL. NOTE: Links are recognized by the prefix "http://" or "https://" and are separated by the next word or character with space. Keep in mind that adding any character like '.' ',' etc, other than space at the end of the link, will be recognized as part of the url and it will result to a shortened url that redirects to a wrong destination.

restrictions

object

[OPTIONAL] Provide the registered Content Template ID and Principal Entity ID to ensure the message is not rejected by TRAI regulations.

transcode

boolean

If “transcode” is set to true/false, then the message body will be/not be transcoded. If the “transcode” parameter is not set, then the application level setting will be used. In case the message can be sent as UTF in one part, it will not be transcoded.

Headers

Content-Type

string

required

Defaults to application/json

application/json

Authorization

string

required

Defaults to Bearer {access_token}

Bearer {access_token}

Responses

Language

Request

Response

Choose an example:

application/json

200200

400400