Fragen? 0800 55400300
View Categories

SMS-API

6 min read

The TENIOS SMS API is performed to send messages via SMS to mobile subscribers and view the message history.

Pre-condition:

  • SMS API enabled in TENIOS Account
  • defined sender-ID (max 11 digits – alphanumeric) (upper-case letters A – Z, lower-case letters a – z, numbers 0 – 9, spaces)
  • use your Account-SID as the username and your Auth Token as the password for HTTP Basic authentication
  • The API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.
  • If the body of a message is more than 160 GSM-7 characters (or 70 UCS-2 characters), we will segment and annotate your messages to attempt proper reassembly on the recipient’s handset (not supported by all carriers and handsets). This ensures your body text transmits with the highest fidelity.

Send SMS:

POST https://sms-api.tenios.com/v2/accounts/{account_sid}/messages

 

Authentification:

account_sid string unique account identifier

Request Parameter:

​

from string A sender-ID to be used as a message sender.
to string Recipient’s phone number. E.164 formatted
text string Text of the message. Max 160 Latin characters or 70 Unicode characters
tag (optional) string Custom tag for filtering

Example:

{
   "from": "SMSCode",
   "to": "491711234567",
   "text": "May the Force be with you",
   "tag": "MyCustomTag"
}

Responses (scheme: application/json):

201 created

status_code integer
status_message string
uri string

 

Example:

{
   "status_code": 201,
   "status_message": "CREATED",
   "uri": "/v2/accounts/{account_sid}/messages/{message_sid}"
}

 

Get Message History

This method allows you to get the status / history of the sent messages.

GET https://sms-api.tenios.com/v2/accounts/{account_sid}/messages

 

Authentification:

account_sid string unique account identifier

Filtering Parameter (optional):

​

account_sid string unique account identifier
message_sid string unique message identifier
number_sid string unique number identifier
from string A sender-ID to be used as a message sender.
to string Recipient’s phone number. E.164 formatted
to_prefix string Recipient’s phone number prefix
direction string Message direction – outbound
status string message statuses: queued – message going to be sent sent – message was sent received – message received by TENIOS API delivered – message delivered by recipient rejected – message rejected, not a valid number unliveable – message was sent, but no delivered expired – message was sent, but no delivered due recipient is not available for 48 hours failed – message was not delivered to the recipient
tag (optional) string Custom tag for filtering
created_after string Messages that were created after this date and time. ‘dateFormat’ => ‘YYYY-MM-DD’
created_before string Messages that were created before this date and time. ‘dateFormat’ => ‘YYYY-MM-DD’
limit string Number of records you want to return per page
prev string URI to the previous page
next string URI to the next page

Example:

GET https://api.apifonica.com/v2/accounts/{account_SID}/messages?created_before=2021-02-01&created_after=2021-01-01

 

GET https://api.apifonica.com/v2/accounts/{account_SID}/messages?created_before=2021-02-01&created_after=2021-01-01

 

Responses (scheme: application/json):

200 OK

status_code integer
status_message string
uri string

 

Example:

{
   "limit": 20,
   "prev": "string",
   "next": "string",
   "messages": [
      {
         "account_sid": "acc45a4971b-8947-31c2-a354-000000000000",
         "number_sid": "num8e8cc997-26fc-0000-a953-000000000000",
         "from": "SMSCode",
         "to": "491702222000",
         "text": "May the Force be with you",
         "direction": "outbound",
         "price": 0.08,
         "status": "delivered",
         "segment_count": 1,
         "tag": "MyCustomTag",
         "created": "Wed, 21 Jul 2021 15:27:56 +0000"
      }
   ]
}

Get Message info/status

The method message info/status allows you to get the info/status for a single message.

GET https://api.apifonica.com/v2/accounts/{account_sid}/messages/{message_sid}

Request Parameter:

​

account_sid string unique account identifier
message_sid string unique message identifier
​

Responses (scheme: application/json):

200 OK ​

account_sid string unique account identifier
number_sid string unique number identifier
message_sid string unique message identifier
from string sender’s number
to string recipient’s number
text string text message
direction string outbound / inbound
price string cost of the transaction (EUR)
status string message statuses: queued – message going to be sent sent – message was sent received – message received by TENIOS API delivered – message delivered by recipient rejected – message rejected, not a valid number unliveable – message was sent, but no delivered expired – message was sent, but no delivered due recipient is not available for 48 hours failed – message was not delivered to the recipient
segment_code integer number of parts in the message
tag string Custom tag for filtering
created string Message creation date

Example:

{
   "account_sid": "acc45a4971b-8947-31c2-a354-000000000000",
   "number_sid": "num8e8cc997-26fc-0000-a953-000000000000",
   "from": "CustomerXYZ",
   "to": "4917011111111",
   "text": "May the Force be with you",
   "direction": "outbound",
   "price": 0.08,
   "status": "delivered",
   "segment_count": 1,
   "tag": "My custom tag",
   "created": "Wed, 21 Jul 2021 15:27:56 +0000"
}

 

Statuses description

  • received: message was received by TENIOS API virtual number (works only for inbound messages)
  • queued: message going to be sent
  • sent: message was sent to a carrier
  • delivered: message delivered to recipient
  • rejected: message rejected, not a valid number
  • undeliverable: message was sent, but no delivered by carrier reason. This can happen for several reasons including carrier content filtering, availability of the destination handset, etc.
  • expired: message was sent, but no delivered due recipient is not available for 48 hours
  • failed: message was not delivered to the recipient by technical or balance reasons

 

Receive SMS

If the virtual number you bought supports 2-way SMS function, then you can receive an incoming SMS to your TENIOS number. To receive incoming SMS, you need to specify a webhook. When you receive incoming SMS to your TENIOS virtual number, you will receive an event on your URL specified in the webhook form.

Structure of the payload body Parameter:

​

account_sid string Unique account identifier. Formatted as uuidv4 with `acc` prefix, like accd00008e2-0000-0000-0000-95c000001f7e.
message_sid string Unique message identifier. Formatted as uuidv4 with `msg` prefix, like msgf0000e27-0000-0000-0000-c0bfe0000dec.
channel string Always has `sms` value.
direction string For inbound messages always has `inbound` value.
from string Sender’s phone number. Formatted as E.164 without `+` symbol, like `4917011111111`.
to string The platform phone number (this is your virtual number). Formatted as E.164 without `+` symbol, like `4917011111111`.
status string For inbound message always has `received` value.
text string The message body for this inbound message.
sms_count integer Count of SMS chunks. If message contains more then 160 GSM-7 symbols would be more then 1.

Examples of events in HTTP format

Depending on the webhook method you have chosen, the event will look like this.

 

Example for POST webhook request:

POST /user-webhook-uri HTTP/1.1 Content-Type: application/x-www-form-urlencoded User-Agent: Go-http-client/1.1 Content-Length: 232 Host: www.userhost.com account_sid=accd00008e2-0000-0000-0000-95c000001f7e&channel=sms&direction=inbound&from=4917011111111&message_sid=msgf0000e27-0000-0000-0000-c0bfe0000dec&sms_count=1&status=received&text=Hello!%20I'm%20new%20customer!&to=4917010000000

 

Example for POST webhook request:

GET /user-webhook-uri?account_sid=accd00008e2-0000-0000-0000-95c000001f7e&channel=sms&direction=inbound&from=4917011111111&message_sid=msgf0000e27-0000-0000-0000-c0bfe0000dec&sms_count=1&status=received&text=Hello!%20I'm%20new%20customer!&to=4917010000000 HTTP/1.1 User-Agent: Go-http-client/1.1 Host: www.userhost.com

 

FAQs:

What if message the received SMS has > 160 characters?

If the SMS have more than 160 GSM-7 symbols, then the full concatenated text of a message will be passed in `text` field of an event and count of segments will be passed on `sms_count` field.

What is the custom tag?

The `tag` field cannot be used for incoming SMS. The `tag` field can be set by the customer only when sending outgoing SMS via the platform API. Then the value will come along with all events for SMS lifecycle. This is a simple text field that a client can use as they see fit. There are several use cases here, from grouping SMS as part of SMS campaigns to placing additional parameters in this field that are necessary for client integration, for example, identifiers of your own clients or your own groups of clients for mapping these values when processing an event on customer side.

 

Error-Message / Response

400 Data Validation Failed

status_code number
error_code number
error_text string
parameters array of strings
errors object
uri string

401 Unauthorized

status_code integer
error_code integer
error_text string
uri string

403 Forbidden

status_code integer
error_code integer
error_text string
uri string

404 Not found

status_code integer
error_code integer
error_text string
uri string

 

TOP