Sending SMS

Description

To send an SMS, it is necessary to make a POST request to the Submit SMS API endpoint.

Production Endpoint URL: https://api.cpaas.symphony.rakuten.net/sms/v1/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
from	Y	This can be either a Sender ID or Number depending on requirement and configuration. Sender addresses must be registered with the operators. Please refer to Sender Addresses.
to	Y	The destination phone number should be in the format: Country Code + Mobile Number (MSISDN) DO NOT prefix "+" or "0" Example: Japanese Mobile Number 070-9830-2393 should be formatted "817098302393"
message_type	Y	This can be either text unicode binary Depending on the value supplied here, it is mandatory to include text_message unicode_message binary_message element in the JSON document.
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
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.

Sample Request

{
  "from": "sender address",
  "to": "...destination phone number...",
  "message_type": "text",
  "text_message": {
    "text": "...message body goes here..."
  }
  "validity_period": {
    "days": "1",
    "hours": "2", 
    "minutes": "45",
    "seconds": "32"
  }
  "metadata": {
    "client_reference": "client-ref-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
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".
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

{
  "result_code": "0",
  "result_message": "Message successfully submitted",
  "client_reference": "...if provided during original request...",
  "message_id": "0000001"
  "how_many_message_parts": 1
}

Sending SMS

Description​

Description