TERA COMMUNICATIONS S.A.

81 Nikola Petkov Blvd. 1619 Sofia, Bulgaria

Phone: +359 2 957 1247 Fax: +359 2 957 1248
www.teracomm.bg

TERACOMM GATEWAY CONNECTIVITY INTERFACE

- HTTP Connectivity v1.0.5 -

TERA COMMUNICATIONS S.A.

81 Nikola Petkov Blvd. 1619 Sofia, Bulgaria
Phone: +359 2 957 1247 Fax: +359 2 957 1248
www.teracomm.bg

Content
1. General description
2. MO messages forwarding
3. Status messages
4. Sending MT messages

Appendix1
Appendix2

TERA COMMUNICATIONS S.A.

81 Nikola Petkov Blvd. 1619 Sofia, Bulgaria
Phone: +359 2 957 1247 Fax: +359 2 957 1248
www.teracomm.bg

1. General description
All communications between Teracomm and Partner is done via
pure HTTP protocol, with optional SSL/TLS layer or IPSEC tunnel.
Partner should provide endpoint URL and list of allowed IP
addresses.
Teracomms
endpoint
URL,
IP
addresses,
authentication
username/password and any other required parameters will be
provided when Partner's account is fully configured.
All parameters in all requests are passed as HTTP/1.1 GET urlencoded parameters.
All request responses should be plain text HTTP responses, with
HTTP/1.1 status code 200 in the header, and a list of space
separated (ASCII code 32 character) strings in the body.

2. MO messages forwarding
When new MO message is received and matched with one of the
predefined keywords, Teracomm sends HTTP(S) request to the
Partner's endpoint URL with the following HTTP GET parameters:

username
password
msg_id
service_id
type

If provided by Partner. Optional field.

If provided by Partner. Optional field.
Unique integer ID of the MO message. Example: 100123
Predefined service id, associated with the list of
predefined keywords/ text prefixes for this service
Type of the request. In this case type=MO

shortcode

The shortcode, that this MO message was sent to.

Example: 1234

msisdn

MSISDN of the mobile customer, with international

prefix. Example: 359888123456

mcc

Mobile country code, as defined in ITU E.212

TERA COMMUNICATIONS S.A.

81 Nikola Petkov Blvd. 1619 Sofia, Bulgaria
Phone: +359 2 957 1247 Fax: +359 2 957 1248
www.teracomm.bg

mnc
text
time

Mobile network code, as defined in ITU E.212

The text of the MO message, UTF-8 string, 160
characters max
The timestamp of the message. Example: 2001-01-01
01:23:45

Partner should respond with plain text OK <msg_id> , where

msg_id should have the same ID as in the HTTP request. Example:

OK 100123

Any other response will be considered error string, and the MO

message forwarding will be retried later, according to the Teracomm
retry schema (see appendix 1).

3. Status messages
When delivery report for a premium/subscription MT message is
received, or a customer subscription is deactivated, Teracomm
sends HTTP(S) request to the Partner's endpoint URL with the
following HTTP GET parameters:

username
password

If provided by Partner. Optional field.

If provided by Partner. Optional field.

msg_id

Unique integer ID of the request. Example: 100124

parent_msg_id

The ID, provided by the Partner in the MT-sending

request.

service_id

Predefined service id, associated with the list of

predefined keywords/ text prefixes for this service

shortcode

The short code, associated with this service.

TERA COMMUNICATIONS S.A.

81 Nikola Petkov Blvd. 1619 Sofia, Bulgaria
Phone: +359 2 957 1247 Fax: +359 2 957 1248
www.teracomm.bg

type
msisdn

Type of the request. In this case type=REPORT

MSISDN of the mobile customer, with international
prefix. Example: 359888123456

mcc

Mobile country code, as defined in ITU E.212

mnc

Mobile network code, as defined in ITU E.212

status

New status. May be one of the following strings:

CHARGED
CHARGE_FAIL
STOPPED

code

Integer code of the error if status=CHARGE_FAIL; value

0 otherwise

text

Description of the error if status=CHARGE_FAIL

time

The timestamp of this message. Example: 2001-01-01

01:23:45

Partner should respond with plain text OK <msg_id> , where

msg_id should have the same ID as in the HTTP request.
Any other response will be considered error string, and the MO
message forwarding will be retried later, according to the Teracomm
retry schema (see appendix 1).
Status CHARGED means that the last premium transaction for that
MSISDN / service was successful.
Status CHARGE_FAIL means that the last premium transaction for
that MSISDN / service was unsuccessful. Partner may retry the
charging request, according to the retry policy, associated with the
error code parameter (see appendix 2)
Status STOPPED means that the customer has requested
deactivation of his subscription, and Partner should send an
appropriate confirmation MT to the customer. After getting this
status, any further charge retry or renew requests from Partner will
be rejected.

TERA COMMUNICATIONS S.A.

81 Nikola Petkov Blvd. 1619 Sofia, Bulgaria
Phone: +359 2 957 1247 Fax: +359 2 957 1248
www.teracomm.bg

4. Sending MT messages
To send an MT message to the customer, Partner needs to send
HTTP(S) request to Teracomm's endpoint URL with the following
HTTP GET parameters:
username
password
msg_id

Username, provided by Teracomm

Password, provided by Teracomm
Unique integer ID of the MT message. Example: 123001

parent_msg_id

Optional. In some cases the MT is requred to be

correlated to an MO, received from the same subscriber.
In this case parent_msg_id should be the same as the
msg_id of the MO request. If not explicitly required in the
service specification, this field can be ommited.

service_id

Predefined service id, provided by Teracomm for this

service. If the type of the message is other than FREE_MT,
the subscriber will be charged with a predefined
amount, assigned to that service_id

Type of the request. One of the following strings:

type

shortcode
msisdn

FREE_MT
PREMIUM_MT
SUBSCRIBE_MT
RENEW_MT
The short code that this MT will be sent from. Example:
1234
MSISDN of the mobile customer, with international prefix.
Example: 359888123456

mcc

Mobile country code, as defined in ITU E.212

mnc

Mobile network code, as defined in ITU E.212

TERA COMMUNICATIONS S.A.

81 Nikola Petkov Blvd. 1619 Sofia, Bulgaria
Phone: +359 2 957 1247 Fax: +359 2 957 1248
www.teracomm.bg

text

The text of the MT message, UTF-8 string, 160 ETSI GSM

03.38 characters max

If the request was handled successfully, Teracomm responds with

plain text OK <msg_id> , where msg_id has the same ID as in
the HTTP request. Example:
OK 123001
If the request cannot be processed for some reason, Teracomm
responds with:
ERROR <msg_id> <error_code> <RETRIABLE|NOT_RETRIABLE>
<error_description>
Example:
ERROR 123001 -1 RETRIABLE Internal_error
If the error is RETRIABLE (as in the example above), or the HTTP
status code is other than 200 (success), Partner should retry the
request without changing any parameters every minute for 1 hour.
If the request is still not processed after that, Partner should
contact Teracomm support for further actions.

TERA COMMUNICATIONS S.A.

81 Nikola Petkov Blvd. 1619 Sofia, Bulgaria
Phone: +359 2 957 1247 Fax: +359 2 957 1248
www.teracomm.bg

Appendix 1
Teracomm retry scheme
Every request from Teracomm to the Partner, that was not
confirmed by the Partner with appropriate response, according to
the specification, will be retried after:
1st retry : 1 minute
2nd retry : 5 minutes
3rd retry : 60 minutes
After that the request will be logged as unsuccessful and no further
actions will be taken. The log of all unsuccessful requests may be
provided to Partner by Teracomm support if required.

TERA COMMUNICATIONS S.A.

81 Nikola Petkov Blvd. 1619 Sofia, Bulgaria
Phone: +359 2 957 1247 Fax: +359 2 957 1248
www.teracomm.bg

Appendix 2
List of Error Codes / Retry policies
Error
code

Retriable / not retriable

Retry policy schema

-1
retriable
Internal error
1
not retriable
Auth fail
2
not retriable
Undefined shortcode
3
not retriable
Undefined service
4
not retriable
Not allowed type for this service
5
not retriable
Invalid type
6
not retriable
Not allowed short code for this service
101
not retriable
The user is not opted in
102
not retriable
The user is already subscribed
103
not retriable
The user is not subscribed
104
not retriable
Renewal attempt before anniversary date
105
not retriable
Missing mandatory text
106*
not retriable
Corresponding MO required
107
not retriable
Over spending limit
200
retriable
Unsuccesful delivery
*There are more MO requests than the attempted MTs send for
markets where the regulation require mandatory 1:1 ratio