RocketCOMS

Create a Campaign Batch

Use a campaign batch to send messages to recipients. The campaign must be successfully registered with The Campaign Registry (TCR) before a batch can be created for the campaign.

You can use the following options to create a campaign batch.

Campaign Batch CSV File

You can upload a CSV file containing the recipient mobile numbers and the message content for the campaign. The CSV file must include the following columns:

  • recipient mobile number
  • message text

For example:

1237774444,New Product Launch This Month
1236663333,New Product Launch This Month

Line breaks are supported in the message with the special character \n (Line Feed). To avoid having an extra space in your message, do not put a space after \n.

For example, enter the message as:
\nHello World
not:
\n Hello World

Note  An SMS message is limited to 140 bytes, which is 160 7-bit characters. Inclusion of 8-bit characters (such as [ ] \ | ) may reduce the number of characters included in the message. For messages over 140 bytes, RocketCOMS will split the message into multiple segments. These segments are then stitched back together into a single message on the subscriber’s mobile device. Because each segment is charged as a separate SMS message, sending long messages may increase the cost to the subscriber. Note that if you’re using URL shortening, RocketCOMS uses the message length after the URLs are shortened to determine if segmentation is required.

Endpoint

POST /v1/batches

Authorization Header

Authorization: Bearer <access_token>
or
Authorization: Basic <encodedString>
where <encodedString> is your <api-key>:<api-secret> string encoded using Base64 encoding

Content-Type Header

multipart/form-data

Query Parameters

campaignId  REQUIRED

string (UUID)

Unique ID assigned to the campaign in RocketCOMS.

externalId  REQUIRED

string

Your organization’s internal reference number assigned to the campaign batch. This reference number is not used by RocketCOMS.

description  

string

Description of the campaign batch.

startDate  REQUIRED

string, format: YYYY-MM-DD

Date to start processing the campaign batch messages. Cannot be a past date.

endDate

string, format: YYYY-MM-DD

Date to stop processing the campaign batch messages. If endDate is not provided, the batch will be processed until all messages are sent.

startTime  REQUIRED

string, format: hh:mm

Time to start processing the campaign batch messages. Messages will only be sent during the period defined by startTime and endTime.

endTime  

string, format: hh:mm

Time to stop processing the campaign batch messages. Messages will only be sent during the period defined by startTime and endTime.

shortlink

boolean, default: false

Whether all URLs in SMS messages will be sent as short links.

action

string enum, values: VALIDATE, SCHEDULE

default value: SCHEDULE

Method used to process a CSV file. Possible values are:

  • VALIDATE  The file will be checked for errors only and will not be processed. Use this option if you want to validate the file and resolve any errors before processing it.

    Use the Retrieve Campaign Batch Errors API to retrieve the error details for the batch file. After resolving any errors, use the Update Campaign Batch File API to upload an updated batch file for processing.

  • SCHEDULE  The file will be checked for errors and then the file will be scheduled for processing.

    Use the Retrieve Campaign Batch Errors API to retrieve the error details for the batch file. Note that you cannot update a batch file once it has been processed.

operationType

string enum, values: CSV_FILE, MESSAGE_TEMPLATE, MANUAL_MESSAGE_INPUT

default value: CSV_FILE

Type of batch operation. Possible values are:

  • CSV_FILE  Upload a CSV file. The file request parameter is required.
  • MESSAGE_TEMPLATE  Use a message template and a recipient list. The messageTemplateId and namedRecipientsListIds parameters are required.
  • MANUAL_MESSAGE_INPUT  Enter a message in the request body and use a recipient list. The message and namedRecipientsListIds parameters are required.

charset

string, values: ASCII, UTF-16

default: ASCII

Character set used for the message.

Request Body

file  REQUIRED

string (binary)

CSV file to upload.

messageTemplateId  CONDITIONAL

string (UUID)

ID of the message template to use for the message content. Required if operationType is set to MESSAGE_TEMPLATE.

namedRecipientsListIds  CONDITIONAL

array

ID of the recipient list to use for the campaign batch. The message will be sent to all recipients on this list. Required when operationType is set to MESSAGE_TEMPLATE or MANUAL_MESSAGE_INPUT.

message  CONDITIONAL

string, max length: 160

Content of the message. Required when operationType is set to MANUAL_MESSAGE_INPUT.

Returns

Returns the Campaign Batch object. This object contains the campaign batch details and status.

SAMPLE RESPONSE

				
					{
  "status": "0000",
  "message": "string",
  "result": {
    "id": "32df8770-ee48-46e7-a8c7-9ec478883076",
    "campaignId": "05ee2300-51cd-4021-b28d-11597cf9a175",
    "description": "Spring Sale",
    "externalId": "a7896",
    "operationType": "MESSAGE_TEMPLATE",
    "message": "string",
    "messageTemplateId": "4a968230-dd15-41fa-9e38-a0abade08b27",
    "namedRecipientsListIds": "cf3775f1-ea90-4378-bdb5-8788f8d1d041",
    "charset": "ASCII",
    "startDate": "2022-04-25",
    "endDate": "2022-04-25",
    "startTime": "02:00:00",
    "endTime": "04:00:00",
    "status": "DELIVERED",
    "createdAt": "2022-04-24T16:51:03.419Z",
    "updatedAt": "2022-04-24T16:51:03.419Z",
    "finishedAt": "2022-04-25T04:00:03.419Z"
  }
}