Send Text Sms To Subscriber

This part of the SMS API enables a third party to send text SMSes to an authorized subscriber. This requires that the API keyholder has the authorization to send to that subscriber, which is set in the to_subscriber field.

It is possible to set the origin address to international numbers, short numbers or a text address. Each of these has specific restrictions based on the rights of the product to the subscriber, as this is based on a matrix of the rights and policies of the subscriber and the product, you must check for rejected messages based on it's content.

All sender IDs must be pre-approved before use. You may configure sender IDs at your product's configuration page on the Developer Portal.

Note that this is a message to the authorized subscriber. If you need to set the from_international field to a specific subscriber, you should rather use the Sending text SMS from subscriber part of the API.

Fragmentation

SMS messages have a normal limit of 160 GSM7 encoded characters, meaning messages larger than that will be fragmented. This fragmentation is handled by the API. If the encoded content is larger than the max limit for a single message we will split the message in fragments than can fit, and the handset will re-assemble them back to a single message.

Encoding

The content field as a general rule uses and supports UTF-8 fully, though as unicode support usually requires software and sometimes firmware upgrades on handsets to be shown correctly, there may be a limit to what characters will show up on the user's handset as intended.

This is a limit on both the protocols used to talk to the handsets, and to the handsets themselves. The API itself is build to support all of unicode, but thus cannot guarantee that everything will show correctly.

The API will detect and attempt to use the most efficient encoding available based on the characters in the text, though the same encoding will be used on all generated fragments.

Limitations

There are also some other restrictions to this API.

• This API cannot send a message to the subscriber that are blocked by subscription policies or quotas.
• This API will not send messages larger than 2000 characters. Note that unicode characters outside of the BMP plane counts as 2 characters each, and number of emoji characters and the newer CJK characters are in this group. Worst case this is 35 fragments for a single message.
• This API does not guarantee that the message is successfully delivered.

Prerequisites

1. An OAuth 2.0 client
2. A client access token

Required Scope

• sms.text:send_to_subscriber is required to use the API function.

Code Dependencies

<dependency>
  <groupId>com.wgtwo.api.v1.grpc</groupId>
  <artifactId>sms</artifactId>
  <version>1.10.1</version>
</dependency>

Code

If targeting production, you would need to add authentication to the sample code.

#!/usr/bin/env bash
grpcurl \
  -d '
  {
    "content": "My text message",
    "fromAddress": "MyProduct",
    "toSubscriber": "+47xxxxxxxx"
  }
  ' \
  sandbox.api.shamrock.wgtwo.com:443 \
  wgtwo.sms.v1.SmsService/SendTextToSubscriber

package com.example.sms

import com.wgtwo.api.v1.sms.SmsProto.SendTextToSubscriberRequest
import com.wgtwo.api.v1.sms.SmsServiceGrpc
import io.grpc.ManagedChannelBuilder

fun main() {
    val channel = ManagedChannelBuilder.forAddress("sandbox.api.shamrock.wgtwo.com", 443).build()
    val stub = SmsServiceGrpc.newBlockingStub(channel)
    val request = SendTextToSubscriberRequest.newBuilder().apply {
        fromAddress = "MyProduct"
        toSubscriber = "+4799999999"
        content = "Hello, World!"
    }.build()
    println("Request:
$request")
    val response = stub.sendTextToSubscriber(request)
    println("Response:
$response")
}

Example Results

{
  "messageId": "6a75356e-6191-11ec-b47d-7382e9b102b6",
  "status": "SEND_STATUS_OK",
  "numFragments": 1
}

message_id: "6a75356e-6191-11ec-b47d-7382e9b102b6"
status: SEND_STATUS_OK
num_fragments: 1

Read More

• SMS API reference
• What is a short message?