Sending an SMS

Discover how to send an A2P SMS

This guide shows you how to send a text SMS and then query it later by its ID.

Endpoints

Below are all APIs url that you will need for this guide:

Transatel APIs	URL
Authentication	https://api.transatel.com/authentication/api
Network SMS	https://api.transatel.com/network/sms

All Transatel APIs are available through our unique API gateway https://api.transatel.com

1. API Authentication

First thing first, let's get your access token by following the getting started guide!

If you need to receive delivery reports (DLR) when sending SMS then you will need to subscribe to the DLR event: NETWORK/SMS/DLR/RECEIVED.

If you haven't registered a data Stream yet, go to the Transatel Console and:

Click the Add data stream button under the Data Stream tab
Select the NETWORK/SMS/DLR/RECEIVED event from the SMS category
Choose your preferred destination type
Fill all the data stream information and click on the Create data stream button

If you already have a data Stream, go to the Transatel Console and:

Click on Edit on the contextual menu (...) of the given data stream under the Data Stream tab
Select the NETWORK/SMS/DLR/RECEIVED event from the SMS category
Click on the Update data stream button

Please check the Data stream page for more information.

3. Check service eligibility (optional)

Now that you are authenticated, and you have an access token, let's use it to check your eligibility to the service. This is of course optional but will help you make sure that your account has all the proper permissions before going further.

To do so, we will use Transatel APIs eligibility mechanism.

The below example shows how to check your eligibility to send an SMS by checking the /api/sms URL:

curl --location --request OPTIONS \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJidXNpbmVzc19lbnRpdGllcyI6WyJBbnkiXSwicHJpbmNpcGFsIjoib2NzLXN1YnNjcmlwdGlvbi1vcmRlci1tYW5hZ2VyIiwic2NvcGUiOlsiQ0FUQUxPR19QUk9EVUNUU19SRUFEX1RFQ0hOSUNBTCIsIkNBVEFMT0dfUFJPRFVDVFNfUkVBRCIsIlVTRVJfUkVBRCIsIklOVkVOVE9SWV9TVUJTQ1JJUFRJT05TX1JFQUQiXSwiZXhwIjoxNjE3MjYwNTYxLCJhdXRob3JpdGllcyI6WyJST0xFX0lOVEVSTkFMX1NZU1RFTSJdLCJqdGkiOiJmOTYwNTFmNS05ZmQzLTQxMDEtYjNkZC0xZjY2Y2Q2MWUzZjIiLCJjbGllbnRfaWQiOiJvY3Mtc3Vic2NyaXB0aW9uLW9yZGVyLW1hbmFnZXIifQ.KBTlltd459_4kPV0O3OfsBTFGBtoqRxG65o_NohK1U7IuJAvIjAa8Fj4Qon1ptFrrTR5M2o8l0f9Dl0D7r0Us6Ej6OsVlFXfQKUiXwVytNUTP7POB6l56Svc5CaVqkXgFKyt7_8h6Ii6R_RteujtSzJSWX7zeLSeemxsxKNtHLLIS_HLyNdQyIsVCZWRfFhdPJVQId_p6B08_A54sAwhrT7qssSbtpG1nGzdqsHdFfaqJt9ABhPedatHNlwcWtCnFthrOrD2rv0Yf8OnRLnt-ZWtypr0cqm6U-brtZeBMhcxgzF4afKlJbKN3K3drPJRrRPjL8L9bf2YvzsDWxY5lA'
\
'https://api.transatel.com/network/sms/api/sms'

Above are highlighted the main information to provide to the API:

Authorization header: This is where you provide the previously retrieved access_token

If successful, the response returned will be as follows:

HTTP/1.1 204 No Content
X-TSL-Request-Id: f6a77025-c2f8-459d-b89a-b52b07abd0df
allow: GET, POST, OPTIONS
...

A successful response will return a HTTP/1.1 204 No Content with the allow header.
This standard HTTP header will contain a list of HTTP methods that you are allowed to use.

GET: Means that you are allowed to search for SMS messages
POST: Means that you are allowed to send SMS messages
OPTIONS: Means here that you can perform an eligibility check

4. Send an SMS

Now that you are authenticated and eligible to the service, let's send your first SMS.

Depending on your use case, you can send either a text or a binary SMS and request an optional delivery report (DLR).

The below example shows how to send an A2P text SMS with DLR:

curl --location --request POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJidXNpbmVzc19lbnRpdGllcyI6WyJBbnkiXSwicHJpbmNpcGFsIjoib2NzLXN1YnNjcmlwdGlvbi1vcmRlci1tYW5hZ2VyIiwic2NvcGUiOlsiQ0FUQUxPR19QUk9EVUNUU19SRUFEX1RFQ0hOSUNBTCIsIkNBVEFMT0dfUFJPRFVDVFNfUkVBRCIsIlVTRVJfUkVBRCIsIklOVkVOVE9SWV9TVUJTQ1JJUFRJT05TX1JFQUQiXSwiZXhwIjoxNjE3MjYwNTYxLCJhdXRob3JpdGllcyI6WyJST0xFX0lOVEVSTkFMX1NZU1RFTSJdLCJqdGkiOiJmOTYwNTFmNS05ZmQzLTQxMDEtYjNkZC0xZjY2Y2Q2MWUzZjIiLCJjbGllbnRfaWQiOiJvY3Mtc3Vic2NyaXB0aW9uLW9yZGVyLW1hbmFnZXIifQ.KBTlltd459_4kPV0O3OfsBTFGBtoqRxG65o_NohK1U7IuJAvIjAa8Fj4Qon1ptFrrTR5M2o8l0f9Dl0D7r0Us6Ej6OsVlFXfQKUiXwVytNUTP7POB6l56Svc5CaVqkXgFKyt7_8h6Ii6R_RteujtSzJSWX7zeLSeemxsxKNtHLLIS_HLyNdQyIsVCZWRfFhdPJVQId_p6B08_A54sAwhrT7qssSbtpG1nGzdqsHdFfaqJt9ABhPedatHNlwcWtCnFthrOrD2rv0Yf8OnRLnt-ZWtypr0cqm6U-brtZeBMhcxgzF4afKlJbKN3K3drPJRrRPjL8L9bf2YvzsDWxY5lA' \
    --data \
    "{ 
      \"mvnoRef\": \"M2MA_WW_TSL_MWC_INTERNAL\",
      \"from\": \"123456\",
      \"to\": \"33612345678\",
      \"type\": \"text\",
      \"text\": \"A picture is worth 1000 words!\",
      \"externalReference\": \"RX12345ZVGT\",
      \"dlr\": true,
    }" \
    'https://api.transatel.com/network/sms/api/sms'

Above are highlighted the main information to provide to the API:

Authorization header: This is where you provide the previously retrieved access_token.
mvnoRef: Customer account identifier provided by Transatel at setup.
from: The originator of the SMS. To be valid, this value should be whitelisted in our system.
to: The recipient of the SMS.
type: The format of the message, text in this case.
text: The content of your SMS.
dlr: Flag to request a delivery report, by default false.

If successful, the response returned will be as follows:

HTTP/1.1 201 Created
X-TSL-Request-Id: d1b7596a-068b-4ee8-9157-980cf7d4498c
Content-Type: application/json
{
  "messageId": "c1e2fac8-0572-4e2c-a487-c3cc5cbbc85c",
  "mvnoRef": "M2MA_WW_TSL_MWC_INTERNAL",
  "creationDate": "2023-04-19T13:30:00Z",
  "createdBy": "<your API user>",
  "direction": "MT",
  "from": "123456",
  "to": "33612345678",
  "type": "text",
  "encoding": "GSM-7",
  "segments": 1,
  "network": "on-net",
  "validityPeriod": 2880,
  "dlr": true,
  "externalReference": "RX12345ZVGT",
  "text": "A picture is worth 1000 words!"
}

A successful response returns a HTTP/1.1 201 Created, meaning that your SMS request was successfully processed and the identifier of your SMS message is returned as messageId.

5. Consult the SMS (optional)

Once your SMS request has been processed, you can consult the detail anytime as follows:

curl --location --request GET \
--header 'Authorization: Bearer
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJidXNpbmVzc19lbnRpdGllcyI6WyJBbnkiXSwicHJpbmNpcGFsIjoib2NzLXN1YnNjcmlwdGlvbi1vcmRlci1tYW5hZ2VyIiwic2NvcGUiOlsiQ0FUQUxPR19QUk9EVUNUU19SRUFEX1RFQ0hOSUNBTCIsIkNBVEFMT0dfUFJPRFVDVFNfUkVBRCIsIlVTRVJfUkVBRCIsIklOVkVOVE9SWV9TVUJTQ1JJUFRJT05TX1JFQUQiXSwiZXhwIjoxNjE3MjYwNTYxLCJhdXRob3JpdGllcyI6WyJST0xFX0lOVEVSTkFMX1NZU1RFTSJdLCJqdGkiOiJmOTYwNTFmNS05ZmQzLTQxMDEtYjNkZC0xZjY2Y2Q2MWUzZjIiLCJjbGllbnRfaWQiOiJvY3Mtc3Vic2NyaXB0aW9uLW9yZGVyLW1hbmFnZXIifQ.KBTlltd459_4kPV0O3OfsBTFGBtoqRxG65o_NohK1U7IuJAvIjAa8Fj4Qon1ptFrrTR5M2o8l0f9Dl0D7r0Us6Ej6OsVlFXfQKUiXwVytNUTP7POB6l56Svc5CaVqkXgFKyt7_8h6Ii6R_RteujtSzJSWX7zeLSeemxsxKNtHLLIS_HLyNdQyIsVCZWRfFhdPJVQId_p6B08_A54sAwhrT7qssSbtpG1nGzdqsHdFfaqJt9ABhPedatHNlwcWtCnFthrOrD2rv0Yf8OnRLnt-ZWtypr0cqm6U-brtZeBMhcxgzF4afKlJbKN3K3drPJRrRPjL8L9bf2YvzsDWxY5lA'
\
'https://api.transatel.com/network/sms/api/sms/c1e2fac8-0572-4e2c-a487-c3cc5cbbc85c'

If successful, the response returned will be as follows (here in the below example the DLR has not yet been received):

HTTP/1.1 200 OK
X-TSL-Request-Id: fd341394-47ed-42a1-92e8-ac696c9255f6
Content-Type: application/json
{
  "messageId": "c1e2fac8-0572-4e2c-a487-c3cc5cbbc85c",
  "mvnoRef": "M2MA_WW_TSL_MWC_INTERNAL",
  "creationDate": "2023-04-19T13:30:00Z",
  "createdBy": "<your API user>",
  "direction": "MT",
  "from": "123456",
  "to": "33612345678",
  "type": "text",
  "encoding": "GSM-7",
  "segments": 1,
  "network": "on-net",
  "validityPeriod": 2880,
  "dlr": true,
  "externalReference": "RX12345ZVGT",
  "text": "A picture is worth 1000 words!"
}

A successful response returns a HTTP/1.1 200 OK with the details of the SMS.

Your SMS messages will be available for consultation for 3 months.

6. Receive DLR event (optional)

If you subscribed to DLR events in step 2, once the DLR is received you will receive a NETWORK/SMS/DLR/RECEIVED event like the one shown below:

{
  "header": {
    "eventId": "627e77fc-7694-4188-8f19-13ca3dbf8f51",
    "eventType": "NETWORK/SMS/DLR/RECEIVED",
    "eventDate": "2023-04-19T13:30:00Z"
  },
  "body": {
    "messageId": "c1e2fac8-0572-4e2c-a487-c3cc5cbbc85c",
    "mvnoRef": "<customer account name>",
    "creationDate": "2023-04-19T13:30:00Z",
    "createdBy": "<your API user>",
    "direction": "MT",
    "from": "123456",
    "to": "33612345678",
    "type": "text",
    "encoding": "GSM-7",
    "segments": 1,
    "network": "on-net",
    "validityPeriod": 2880,
    "dlr": true,
    "dlrDate": "2023-04-19T13:30:30Z",
    "dlrStatus": "delivered",
    "externalReference": "RX12345ZVGT",
    "text": "A picture is worth 1000 words!"
  }
}

You will be able to identify the SMS delivery report event thanks to the eventType and messageId.

Additionally, you can check the generated events directly in the Transatel Console under the Data stream tab, by clicking on Details on the contextual menu (...) of the data stream and select the Events tab. This tab will give you access to the event delivery history and status for your data stream.

To learn more about the definition of this event, please check the network events page.

What to do next?

Learn more about our Network SMS API by checking the overview & API reference: