SMS-API - Tenios

Dokumentation

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