post

/sms/v1/{subAccountId}/many

About the API endpoint / method

  • Sending a POST request to this endpoint allows to send SMS by batches (1 request for multiple SMS) with personalized contents/properties.
  • It is ideal to send marketing campaigns or any kind of mass personalized announcement. To send a batch of identical SMS, it is easier to use the many/compact end-point.
  • Using this API, it is possible to send up to 10,000 SMS per request.

URL

The Wavecell subaccountid to use is defined in the URL where you send your POST request as shown below:

https://api.wavecell.com/sms/v1/{subAccountId}/many

You must replace {subAccountId} in the URL above with the subaccountid that you want to use.

Authorization

apiKey - Authorization

Request Parameters

1 Path Parameter
1 Header

Request Body

Request structure

To send many SMS using the Wavecell SMS API you need to submit a JSON-formatted request with the following elements:

Name Type Description Required
messages array Array containing multiple SmsRequest objects (see Single doc) Required
clientBatchId string Unique ID that you want to associate with the batch of SMS Optional
template object Object applying common properties to the SmsRequest objects in messages Optional
includeMessagesInResponse boolean Boolean defining if the API response should contain the SMS details Optional

About the template object

  • The many endpoint incorporates a new logic with the template object.
  • The purpose of this object is to let you specify the common properties of the SMS contained in the messages into a single object.
  • The best practice is to only incorporate the unique properties of each SMS in the SmsRequest objects contained in the messages array while specifying the common properties in the template object.
  • The template object is optional in the request.

The template object can take the following parameters:

Name Type Description Required
text string SMS body (ie: text of the message) Required
source string Alphanumeric or numeric string used as Sender ID for the SMS Optional
encoding string Character set to use for this SMS - The possible values are AUTO - GSM7 - UCS2 Optional
scheduled timestamp Pre-defined date and time for this SMS to be sent in the future Optional
expiry timestamp Maximum date and time for this SMS to be sent at Optional
dlrCallbackUrl uri Webhook URL where delivery status for the SMS will be posted (Overwrites your default account callback URL). Optional
2 Examples
Schema
object

Request object to send batch of SMS

clientBatchId
string

Client managed id for this batch of messages : your own unique reference

1 validation
messages
array[object]
2 validations + required
template
object
2 validations
includeMessagesInResponse
boolean

Determines whether the reponse should include individual details for each message sent

Responses

  • The response returns two different IDs for the batch:

    • batchId: the unique batch ID generated automatically by Wavecell
    • clientBatchId: the batch ID that you submitted in the request (if any)
  • It also returns a summary of the batch submission:

    • acceptedCount: number of SMS accepted by the API
    • rejectedCount: number of SMS rejected by the API
  • If the includeMessagesInResponse boolean has been set to True during the request, it also returns an array containing individual information for each SMS submitted to the API in the many request:

    • umid: unique message ID automatically generated by Wavecell
    • clientMessageId: message ID that you submitted (if any)
    • destination: destination phone number to which the SMS was sent to
    • encoding: SMS encoding - GSM7 or UCS2
  • And then it returns a status object containing the following:

    • status code: the status code can be either:
      • QUEUED: the SMS has been accepted by Wavecell API and is queued for processing.
      • REJECTED: the SMS has been rejected by Wavecell API and the reason is stated in the description field. It will not be processed.
    • description: this field describes the status code and provides additional information explaining the status. It can take the following values:
      • SMS is accepted and queued for processing (QUEUED Status)
      • Text value is missing (REJECTED Status)
      • Invalid Text value. Reached max allowed limit (REJECTED Status)
      • Invalid Source value. Reached max allowed limit (REJECTED Status)
      • Expiry time already reached (REJECTED Status)
      • Invalid MSISDN format (not E.164 international number) (REJECTED Status)
      • Internal server error (REJECTED Status)
1 Example
Schema
object

Response object of sending batch of SMS

batchId
string

Unique batch id (guid) generated by Wavecell platform upon batch submission

1 validation + required
clientBatchId
string

Client managed id for this batch of messages : your own unique reference

acceptedCount
integer

Amount of accepted messages

required
rejectedCount
integer

Amount of rejected messages

required
messages
array[object]

List of processed messages (if flag includeMessagesInResponse=true)

Send a Test Request

Send requests directly from the browser (CORS must be enabled)
Path Params
subAccountId
$$.env
Authorization
subAccountId