Sending Multi-SMS
Description
To send multiple SMS messages, you need to make a POST request to the Multi SMS API endpoint, providing an array of sms_messages objects that contain the different messages.
Production Endpoint URL: https://api.cpaas.symphony.rakuten.net/sms/v1/multi/submit
Methods: POST
HTTP Headers
| Parameter | Required | Value |
|---|---|---|
| Authentication | Y | Type: Bearer Token: JWT Token |
| Accept | Y | application/json |
| Content-Type | Y | application/json; charset=UTF-8 |
Request Body Schema: application/json
| Parameter | Required | Description/Values |
|---|---|---|
| sms_messages | Y | An array of objects representing individual SMS messages. Each object includes required parameters
|
| from | Y | This can be either a Sender ID or Number depending on requirement and configuration. es must be registered with the operators. Please refer to es. |
| to | Y | The destination phone number should be in the format: Country Code + Mobile Number (MSISDN)
|
| message_type | Y | This can be either
|
| text_message | Conditional | If message_type = text, then include this element |
| ┗text | This describes a regular 7/8 bit text message sent using the GSM Alphabet. (GSM Alphabet is used for English alphabet) By default, the text field is split over multiple concatenated messages automatically, however, if you wish to handle concatenation manually, you may send individual message parts by specifying the text of the individual segment here along with its corresponding UDH as a hex string. For concatenated messages, maximum characters allowed: 1520 For line breaks add "/n" which is counted as 1 character Note: Refer to the Concatenated Message Splitting section for the details on how concatenated messages are split as per message type and character length | |
| ┗udh | HEX string for UDH | |
| unicode_message | Conditional | If message_type = unicode, then include this element |
| ┗text | This describes a Unicode text message sent using the UCS-2 Alphabet (UCS-2 Alphabet is used for Japanese text). By default, the text field is split over multiple concatenated messages automatically, however, if you wish to handle concatenation manually, you may send individual message parts by specifying the text of the individual segment here along with its corresponding UDH as a hex string. For concatenated messages, maximum characters allowed: 660 For line breaks add "/n" which is counted as 1 character Note: Refer to the Concatenated Message Splitting section for the details on how concatenated messages are split as per message type and character length | |
| ┗udh | HEX string for UDH | |
| binary_message | Conditional | If message_type = binary, then include this element |
| ┗body | This describes a binary message. There is no automatic concatenation with a binary message so the body and udh content specified here should fit within a single 140 byte GSM message. Binary messages are used to send data rather than plan text and will not be used for standard SMS use-cases. | |
| ┗udh | HEX string for UDH | |
| template_message | Conditional | If message_type = template, then include this element |
| ┗template_id | This refers to the configured template id. The template can be configured using a regular 7/8 bit text message sent using the GSM Alphabet, which has a character limit of 1520. The template can also be defined using the UCS-2 Alphabet (UCS-2 Alphabet is used for Japanese text), which has a character limit of 660. By default, the text is split over multiple concatenated messages automatically. Note: Refer to the Concatenated Message Splitting section for the details on how concatenated messages are split as per message type and character length | |
| ┗substitutions | This is an 'array' type with multiple name/value elements inside it. The name/values pairs should be substituted in the template with actual values e.g., For template "Hi ${fname}" where ${fname} can be substituted by passing | |
| ┗name | fname | |
| ┗value | John | |
| validity_period | Optional | This allows you to specify the validity period for this message, i.e., how long it will remain in the network attempting to reach the destination handset before giving up. This period can be expressed in hours, minutes, seconds, or with a raw SMPP format validity period string, passing either an absolute or relative time period. The fields in this element (days, hours, minutes, or seconds) may be combined. Note: Refer to the Maximum Validity Period section for the details per MNO |
| ┗days | ||
| ┗hours | ||
| ┗minutes | ||
| ┗seconds | ||
| ┗smpp_validity_period_string | Validity period expressed in SMPP format Note: To be used by advanced users only - refer appropriate GSM specifications for more details e.g. http://smpp.org/SMPP_v3_4_Issue1_2.pdf | |
| delivery_receipts | Optional | This element is required if you wish to receive a delivery receipt relating to this SMS message submission. You can specify whether or not you wish to receive a delivery receipt (the default is false if this is not specified), optionally you can also elect to receive intermediate delivery receipts where these are supported by the downstream network. Intermediate delivery receipts are delivery receipts when messages are in the process of reaching the handset, thus the message has still not been received by the handset. Finally, you have the option here to specify a Webhook URL to receive the delivery receipt. If specified, this overrides the URL that was configured in the user dashboard as part of the account setup. By default, the URL from the user dashboard will be used if nothing is specified here in the API request |
| ┗required | true or false | |
| ┗intermediate_dlr | true or false | |
| ┗custom_callback_url | The callback URL where delivery receipt should be received e.g. https://<WEBHOOK URL> | |
| advanced_settings | Optional | These elements allow additional control over the message that is being sent. These values may need to be set for specialist use cases. If you are making use of this element, it is assumed that you are familiar with the meaning of the fields within and of the supported values. Note: To be used by advanced users only - refer appropriate GSM specifications for more details e.g. http://smpp.org/SMPP_v3_4_Issue1_2.pdf |
| ┗message_class | 0, 1, 2 or 3 | |
| ┗message_waiting_indicator | 1 or 2 | |
| ┗protocol_id | 0 – 255 | |
| metadata | Optional | This element allows you to attach a unique client reference to the message. This value will be reflected and passed back in the API response, as well as in any subsequent delivery receipt Webhook calls that are related to this message. |
| ┗client_reference | The client_reference field is a free form text field that may contain up to 50 characters. | |
| correlation_id | Optional | The correlation_id is a free form text field that may contain up to 50 characters. This allows for all of the messages in the request to be linked together (this value is presented in the DLR) |
Sample Request
{
"sms_messages": [
{
"from": "sender address",
"to": "destination-phone-number-1",
"message_type": "text",
"text_message": {
"text": "message #1"
},
"validity_period": {
"days": "1",
"hours": "2",
"minutes": "45",
"seconds": "32"
},
"metadata": {
"client_reference": "client-ref-1"
}
},
{
"from": "sender address",
"to": "destination-phone-number-2",
"message_type": "text",
"text_message": {
"text": "message #2"
},
"validity_period": {
"days": "1",
"hours": "2",
"minutes": "45",
"seconds": "32"
},
"metadata": {
"client_reference": "client-ref-2"
}
},
{
"from": "sender address",
"to": "destination-phone-number-3",
"message_type": "text",
"text_message": {
"text": "message #3"
},
"validity_period": {
"days": "1",
"hours": "2",
"minutes": "45",
"seconds": "32"
},
"metadata": {
"client_reference": "client-ref-3"
}
},
{
"from": "sender address",
"to": "destination-phone-number-4",
"message_type": "text",
"text_message": {
"text": "message #4"
},
"validity_period": {
"days": "1",
"hours": "2",
"minutes": "45",
"seconds": "32"
},
"metadata": {
"client_reference": "client-ref-4"
}
},
{
"from": "sender address",
"to": "destination-phone-number-5",
"message_type": "text",
"text_message": {
"text": "message #5"
},
"validity_period": {
"days": "1",
"hours": "2",
"minutes": "45",
"seconds": "32"
},
"metadata": {
"client_reference": "client-ref-5"
}
},
{
"from": "sender address",
"to": "destination-phone-number-6",
"message_type": "text",
"text_message": {
"text": "message #6"
},
"validity_period": {
"days": "1",
"hours": "2",
"minutes": "45",
"seconds": "32"
},
"metadata": {
"client_reference": "client-ref-6"
}
},
{
"from": "sender address",
"to": "destination-phone-number-7",
"message_type": "text",
"text_message": {
"text": "message #7"
},
"validity_period": {
"days": "1",
"hours": "2",
"minutes": "45",
"seconds": "32"
},
"metadata": {
"client_reference": "client-ref-7"
}
},
{
"from": "sender address",
"to": "destination-phone-number-8",
"message_type": "text",
"text_message": {
"text": "message #8"
},
"validity_period": {
"days": "1",
"hours": "2",
"minutes": "45",
"seconds": "32"
},
"metadata": {
"client_reference": "client-ref-8"
}
},
{
"from": "sender address",
"to": "destination-phone-number-9",
"message_type": "text",
"text_message": {
"text": "message #9"
},
"validity_period": {
"days": "1",
"hours": "2",
"minutes": "45",
"seconds": "32"
},
"metadata": {
"client_reference": "client-ref-9"
}
},
{
"from": "sender address",
"to": "destination-phone-number-10",
"message_type": "text",
"text_message": {
"text": "message #10"
},
"validity_period": {
"days": "1",
"hours": "2",
"minutes": "45",
"seconds": "32"
},
"metadata": {
"client_reference": "client-ref-10"
}
}
],
"correlation_id": "correlation-id-1"
}
Response:
If successful, the API call will return an HTTP 200 OK with a JSON document as a response. Please see section "Errors/Rejections of Submit SMS API Request" for a description of the failure responses.
| Parameter | Description |
|---|---|
| smsResponses | An array of objects that provide detailed information about the status of each SMS message sent. Each object includes |
| result_code | Refer Result Code List |
| result_message | Description of the result code |
| client_reference | Client reference is returned only when specified in request. |
| correlation_id | Correlation ID is returned only when specified in request. |
| message_id | Auto-generated Id |
| how_many_message_parts | This shows how many parts the message was split into e.g., for 1520 chars’ long message, the value will be 10 |
Sample Response
{
"smsResponses" : [
{
"result_code" : 0,
"result_message" : "Message successfully submitted",
"client_reference" : "client-ref-1",
"message_id" : "message-id-1",
"how_many_message_parts" : 1
},
{
"result_code" : 0,
"result_message" : "Message successfully submitted",
"client_reference" : "client-ref-2",
"message_id" : "message-id-2",
"how_many_message_parts" : 1
},
{
"result_code" : 0,
"result_message" : "Message successfully submitted",
"client_reference" : "client-ref-3",
"message_id" : "message-id-3",
"how_many_message_parts" : 1
},
{
"result_code" : 0,
"result_message" : "Message successfully submitted",
"client_reference" : "client-ref-4",
"message_id" : "message-id-4",
"how_many_message_parts" : 1
},
{
"result_code" : 0,
"result_message" : "Message successfully submitted",
"client_reference" : "client-ref-5",
"message_id" : "message-id-5",
"how_many_message_parts" : 1
},
{
"result_code" : 0,
"result_message" : "Message successfully submitted",
"client_reference" : "client-ref-6",
"message_id" : "message-id-6",
"how_many_message_parts" : 1
},
{
"result_code" : 0,
"result_message" : "Message successfully submitted",
"client_reference" : "client-ref-7",
"message_id" : "message-id-7",
"how_many_message_parts" : 1
},
{
"result_code" : 0,
"result_message" : "Message successfully submitted",
"client_reference" : "client-ref-8",
"message_id" : "message-id-8",
"how_many_message_parts" : 1
},
{
"result_code" : 0,
"result_message" : "Message successfully submitted",
"client_reference" : "client-ref-9",
"message_id" : "message-id-9",
"how_many_message_parts" : 1
},
{
"result_code" : 0,
"result_message" : "Message successfully submitted",
"client_reference" : "client-ref-10",
"message_id" : "message-id-10",
"how_many_message_parts" : 1
}
],
"correlation_id" : "correlation-id-1"
}
Sample Request with Template
{
"sms_messages": [
{
"from": "sender address",
"to": "destination-phone-number-1",
"message_type": "template",
"template_message":
{
"template_id": "template-id-1",
"substitutions": [
{
"name": "fname",
"value": "John"
}
]
},
"validity_period": {
"days": "1",
"hours": "2",
"minutes": "45",
"seconds": "32"
},
"metadata": {
"client_reference": "client-ref-1"
}
},
{
"from": "sender address",
"to": "destination-phone-number-2",
"message_type": "template",
"template_message": {
"template_id": "template-id-1",
"substitutions": [
{
"name": "fname",
"value": "Jane"
}
]
},
"validity_period": {
"days": "1",
"hours": "2",
"minutes": "45",
"seconds": "32"
},
"metadata": {
"client_reference": "client-ref-2"
}
},
{
"from": "sender address",
"to": "destination-phone-number-3",
"message_type": "template",
"template_message": {
"template_id": "template-id-1",
"substitutions": [
{
"name": "fname",
"value": "Jill"
}
]
},
"validity_period": {
"days": "1",
"hours": "2",
"minutes": "45",
"seconds": "32"
},
"metadata": {
"client_reference": "client-ref-3"
}
}
]
}
Response:
If successful, the API call will return an HTTP 200 OK with a JSON document as a response. Please see section "Errors/Rejections of Submit SMS API Request" for a description of the failure responses.
| Parameter | Description |
|---|---|
| smsResponses | An array of objects that provide detailed information about the status of each SMS message sent. Each object includes |
| result_code | Refer Result Code List |
| result_message | Description of the result code |
| client_reference | Client reference is returned only when specified in request. Information on attaching "client reference" can be found under "Additional/Advanced Options". |
| correlation_id | Correlation ID is returned only when specified in request. |
| message_id | Auto-generated Id |
| how_many_message_parts | This shows how many parts the message was split into e.g., for 1520 chars’ long message, the value will be 10 |
Sample Response
{
"smsResponses" : [
{
"result_code" : 0,
"result_message" : "Message successfully submitted",
"client_reference" : "client-ref-1",
"message_id" : "message-id-1",
"how_many_message_parts" : 1
},
{
"result_code" : 0,
"result_message" : "Message successfully submitted",
"client_reference" : "client-ref-2",
"message_id" : "message-id-2",
"how_many_message_parts" : 1
},
{
"result_code" : 0,
"result_message" : "Message successfully submitted",
"client_reference" : "client-ref-3",
"message_id" : "message-id-3",
"how_many_message_parts" : 1
}
"correlation_id" : "correlation-id-1"
}
