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
Webhooks	https://api.transatel.com/webhooks/api

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 create a webhook and subscribe to the DLR event: NETWORK/SMS/DLR/RECEIVED.
Please check the integration guide to learn more about it.

To do so, we will use the Webhooks API.

The below example shows how to create a webhook and subscribe to DLR events:

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\",
      \"status\": \"active\",
      \"targetUrl\": \"https://example.com/events\",
      \"events\": [
        \"NETWORK/SMS/DLR/RECEIVED\"
      ]
    }" \
    'https://api.transatel.com/webhooks/api/webhooks'

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 name provided by Transatel at setup
targetUrl: The HTTPS url to which events will be posted
events: An array with the events you want to subscribe to, here the DLR event

If successful, the response returned will be as follows:

HTTP/1.1 201 Created
  Content-Type: application/json
  {
    "id": "257728ad-01ed-447d-b923-062604926f95",
    "mvnoRef": "M2MA_WW_TSL_MWC_INTERNAL",
    "status": "active",
    "targetUrl": "https://example.com/events",
    "events": [
      {
        "eventType": "NETWORK/SMS/DLR/RECEIVED",
        "description": "A delivery report (DLR) has been received for a previously sent SMS message",
        "domain": "NETWORK",
        "category": "sms",
        "_links": {
          "doc": {
            "href": "https://developers.transatel.com/api/network/events/#tag/SMS/paths/NETWORK~1SMS~1DLR~1RECEIVED/post"
          }
        }
      }
    ],
    "_links": {
      "self": {
        "href": "https://api.transatel.com/webhooks/api/webhooks/257728ad-01ed-447d-b923-062604926f95"
      }
    }
  }

A successful response returns a HTTP/1.1 201 Created with the details of the webhook.

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
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
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
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.

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:

Sending an SMS

Endpoints

1. API Authentication

2. Subscribe to DLR events (optional)

3. Check service eligibility (optional)

4. Send an SMS

5. Consult the SMS (optional)

6. Receive DLR event (optional)

What to do next?