API Docs

Send text SMS from subscriber

This part of the SMS API enables a third party to send out text SMSes on behalf of an authorized subscriber. This required that the API key holder has the authorization to send on behalf of that subscriber, which is set in the from_subscriber field.

FieldDescription
from_subscriberThe E.164 number with '+' of the subscriber.

The destination number can be set to international or short numbers. Which numbers is allowed is based on a matrix of rights for the product and subscriber, so you must check for rejected messages based on it's content.

FieldContentDescription
to_address+numberAn international number in E.164 format with a '+'.
to_addressnumberA short format or network specific number in the national format. Numbers resolving to international must be entered as international.

Note that using this API may incur costs or quota uses to the subscriber. Any such cost will be based on the number of fragments sent. See the response num_fragments field for details.

Fragmentation and Encoding

Fragmentation and message encoding is handled the same way as for messages to subscriber.

Limitations

There are also some other restrictions to this API.

  • This API cannot send a message from the subscriber that are blocked by subscription policies or quotas, i.e. messages that the subscriber is not allowed to send from the handset itself.
  • 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_from_subscriber is required to use the API function.

Code

TIP

You can test our APIs without authorization by targetting sandbox.api.wgtwo.com instead of api.wgtwo.com and removing any authorization from the request/code sample.

Download proto definitions
curl -sL 'https://github.com/working-group-two/wgtwoapis/blob/master/image.bin?raw=true' -o wgtwo.bin
1
export ACCESS_TOKEN="my_client_access_token"
grpcurl -protoset wgtwo.bin \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '
  {
    "content": "My text message",
    "fromSubscriber": "+47xxxxxxxx",
    "toAddress": "+47yyyyyyyy"
  }
  ' \
  api.wgtwo.com:443 \
  wgtwo.sms.v1.SmsService/SendTextFromSubscriber
1
2
3
4
5
6
7
8
9
10
11
12

Example result

{
  "messageId": "6a75356e-6191-11ec-b47d-7382e9b102b6",
  "status": "SEND_STATUS_OK",
  "numFragments": 1
}
1
2
3
4
5
Install dependencies

Maven

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

package com.example.sms

import com.wgtwo.api.v1.sms.SmsProto.SendTextFromSubscriberRequest
import com.wgtwo.api.v1.sms.SmsServiceGrpc
import com.wgtwo.auth.BearerTokenCallCredentials
import io.grpc.ManagedChannelBuilder

/** Use the sandbox environment for testing without authentication */
private val environment = Environment.SANDBOX

private val endpoint = when (environment) {
    Environment.SANDBOX -> "sandbox.api.wgtwo.com"
    Environment.PRODUCTION -> "api.wgtwo.com"
}
private val channel = ManagedChannelBuilder.forAddress(endpoint, 443).build()
private val stub = SmsServiceGrpc.newBlockingStub(channel).apply {
    /**
     * If you are not using the sandbox, you need to add credentials.
     * The BearerTokenCallCredentials class can be found in our auth library.
     */
    if (environment == Environment.PRODUCTION) {
        this.withCallCredentials(BearerTokenCallCredentials { "MY_CLIENT_ACCESS_TOKEN" })
    }
}

fun main(vararg args: String) {
    require(args.size == 3) { "This program requires 3 arguments: from-number to-number content" }

    val request = SendTextFromSubscriberRequest.newBuilder().apply {
        fromSubscriber = args[0]
        toAddress = args[1]
        content = args[2]
    }.build()
    println("Request:\n$request")
    val response = stub.sendTextFromSubscriber(request)
    println("Response:\n$response")

    channel.shutdownNow()
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

Example result

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

Read more