Version No 3.2.0

Introduction


Welcome to our SMS API documentation, where you can seamlessly integrate messaging capabilities into your web application. Our SMS API offers a straightforward implementation, making it easy for you to send messages directly from your application to enhance user engagement.

Turkey SMS API Documentation

Whether you are looking to send notifications, alerts, or any other type of SMS, our API provides a reliable and efficient solution. This documentation will guide you through the necessary steps to integrate our SMS API seamlessly into your web application.

SMS API Service


Welcome to our SMS API service, designed to easily enable SMS functionality for your website, application, or customer relationship management platform through our comprehensive RESTful API.

Programmatic linking via the API allows you to establish seamless connections between your messaging service account and external applications, such as websites, mobile apps, accounting programs, and customer management systems. The SMS system supports all major programming languages including PHP, JAVA, C++, and ASP.

You can initiate the linking process by accessing the direct linking option in your account after logging in. Our system will guide you through the linking process effortlessly.

Wondering about additional costs for direct linking? Rest assured, there are no extra charges for the programmatic linking process. Our dedicated technical support team is also available to assist you in setting up and fully configuring the direct linking.

Requirements


Before utilizing the API service, ensure that your account meets the following conditions to establish a correct and problem-free connection with the messaging service:

Active Account Your account must be active in the messaging service, and your control panel should be fully activated.
Message Balance Maintain a sufficient message balance in your account to utilize the API.
Verified Sender ID Ensure your account has a fully verified Sender ID.

Get Started


Kickstart your integration with the SMS API by following these simple steps:

  1. Log in to your account.
  2. Navigate to the main menu and select "My Account" and then "API Settings."

Turkey SMS API Documentation

In the API Settings section, you'll find essential information related to your account that you'll need to begin using the SMS API service efficiently.

Authenticate


To connect to the SMS API, use the following URL address:

/api/v3/authenticate/login

Parameters

								
$api_key  = '';
$report   = '';
$response_type = '';
								
							

Parameter Descriptions

$api_key varchar Your API key from your account.
$report int Option to display the details of the sending process (1 for report, 0 for cancellation).
$response_type int Type of response (JSON or Array).

Example Responses (if the report option is enabled)

Response Code

Array
(
    [result] => true
    [result_code] => TS-1046
    [result_message] => operation_success
    [user_id] => USERID
    [account_name] => ACCOUNTNAME
)
							

Response Details

result Operation result (true for success, false for failure).
result_code Status code (refer to Response Code for the list of codes).
result_message Message regarding the success or failure of the operation.
user_id The account ID for which authentication was performed is displayed via the API.
account_name The account Name for which authentication was performed is displayed via the API.

Sending SMS POST


To connect to the SMS API, use the following URL address:

turkeysms.com.tr/api/v3/gonder/add-content

Parameters

								
$title    = '';
$api_key  = '';
$text	  = '';
$sentto	  = '';
$report   = '';
$sms_lang = '';
$response_type = '';
								
							

Parameter Descriptions

$title varchar Your Sender ID as it appears in your account.
$api_key varchar Your API key from your account.
$text text The message text.
$sentto int Recipient's mobile phone number.
$report int Option to display the details of the sending process (1 for report, 0 for cancellation).
$sms_lang int Encoding of the message text, with UTF-8 as default.
$response_type int Type of response (JSON or Array).
$content_type int The type of content being sent in the SMS message. This parameter helps define the nature of the message, and it accepts the following values:
  • 0: Transactional - Indicates a message related to a transaction or user interaction.
  • 1: High Quality - Represents a message with high-quality content, possibly marketing or informational.
  • 2: Advertising - Specifies an advertising message intended for promotional purposes.
The actual content type is determined based on the value assigned to this parameter in your API request.

Example Responses (if the report option is enabled)

Response Code

Array
(
    [result] => true
    [sms_id] => 1000007721
    [total_has_sent_last_1_min] => 1
    [number_of_sms] => 1
    [result_code] => TS-1024
    [result_message] => The message was sent successfully
    [sms_lang] => Arabic
    [content_type] => Transactional
    [country] => Turkey-TR
)
							

Response Details

result Operation result (true for success, false for failure).
sms_id Message ID (length may vary).
number_of_sms Number of used credits.
result_code Status code (refer to Response Code for the list of codes).
result_message Message regarding the success or failure of the operation.
sms_lang Language of the sent message.
content_type Type of content being sent in the SMS message (Transactional, High Quality, Advertising).
total_has_sent_last_1_min Total number of messages sent in the last 1 minute.
country Country to which the message was sent.

Sending SMS via GET


Learn how to send a message through the API using the GET format. Sending messages via GET is a straightforward and simple process.

Variables and options are appended to the link, just like the examples mentioned above. The link structure is as follows:

								
api/v3/get/get.php?api_key=API_KEY_HERE&mobile=MOBILE_HERE&title=TITLE_HERE&text=SMS_TEXT_HERE&report=1&lang=2&response_type=json&content_type=0
								
							

In a GET request, data is sent in the URL itself, making it visible and easy to understand. The parameters are appended to the URL after a question mark (`?`), and each parameter-value pair is separated by an ampersand (`&`). This simplicity makes it convenient for testing and quick integration.

It's important to note that due to the visibility of data in the URL, sensitive information should not be passed through GET requests for security reasons. For sensitive data, it's recommended to use the POST method.

Sending OTP SMS


The OTP service, short for "One Time Passcode," generates a randomly created code for one-time use. This code is sent via SMS and is utilized in verification processes, login procedures, and account confirmations. OTP is often used in two-factor authentication to enhance security for your login processes. One key feature of OTP is that the password is usable for only one time, providing added security against hacking and password guessing attempts.

Noteworthy, the OTP service excels in delivering messages at a faster rate compared to other types of messages.
Additionally, OTP service does not require an activated sender ID in the customer's account, and there is no control over the message content as it is solely for verification code purposes.

The direct API link for sending SMS OTP via [GET] is:

/api/v3/otp/otp_get.php

The variables sent through the link are:

								
$api_key  = '';
$mobile   = '';
$digits   = '';
$report   = '';
$lang     = '';
$response_type = '';
								
							

Explanation of the variables sent through the link:

api_key$ varchar Your API key placed here.
mobile$ int The recipient's number. It should not contain letters or symbols.
digits$ int The number of digits in the verification code.
report$ int Option to display the delivery report. 1 for display, 0 to cancel.
lang$ int Language option for the sent message. 2 for Arabic, 0 for English.
response_type$ int Option to display the server response in a specific programming language.

After the sending process, the server will respond with the following:

Example response from the server after the sending process:

								
Array
(
	[result] => true
	[otp_code] => 123456
	[sms_id] => 1000007721
	[number_of_sms] => 1
	[result_code] => TS-1024
	[result_message] => The message was sent successfully
	[sms_lang] => Arabic
	[country] => Turkey-TR
)
								
							

Explanation of the variables sent from the server:

result The result of the process. "true" indicates success, "false" indicates failure.
otp_code The verification code sent in the message to the recipient.
sms_id The recorded ID of the process, which allows tracking the message's status.
number_of_sms The number of messages or credits deducted from your account after sending the message.
result_code The process code. Refer to the sending codes section for complete details.
result_message The message from the sent process. It displays a message about the success or failure of the process.
sms_lang The language of the sent message.
country The name of the country to which the message was sent.

OTP SMS Options

digits$ Specifies the number of digits in the code to be sent.
If the value is 4, the code will be 4 digits [0000].
If the value is 5, the code will be 5 digits [00000].
If the value is 6, the code will be 6 digits [000000].

Message Content Language Options

sms_lang$ If the value for this variable is 0, the message content will be in English.
If the value is 1, the message content will be in Turkish, supporting Turkish characters.
If the value is 2, the message content will support the Arabic language.

Response Option

response_type$ If the value of the variable is json, the response will be in JSON format.
If the value is php, the response will be in PHP format.

Response Codes


When sending a message via the direct API connection, the server will respond with a code to indicate the outcome of the process. These codes provide information about the result of the operation you have performed.

Response Codes

TS-1024 Message sent successfully
TS-1025 The mobile number has not been entered. The phone number is empty
TS-1026 Message text is empty .. No message text has been written
TS-1027 There is insufficient balance in your account
TS-1028 Sender ID is not active for your account
TS-1029 The Sender ID does not exist .. Please make sure you type correctly
TS-1030 Your account is inactive with the SMS service provider
TS-1031 The api-key is invalid
TS-1032 The number to which the message is sent is international outside Turkey. Your account is not activated for international SMS
TS-1033 The data sent through the link is incorrect
TS-1034 The mobile number to which the message was sent is invalid
TS-1060 Exceeded the limit of the number of messages in the last minute
TS-1061 Contact key is not active for sending (POST)
TS-1062 Contact key is not active for sending (GET)
TS-1050 Contact key is empty and not written
TS-1051 Sending title is empty and not written
TS-1052 Message ID is not written
TS-1063 Checking message status is not active for the contact key
TS-1064 Message status check is successful
TS-1065 Checking balance is not active for your account's contact key
TS-1022 The number did not receive the message
TS-1023 The number out of coverage did not receive the message yet
TS-1070 Scheduled Sending - Date not specified or invalid. Please enter a valid date.
TS-1071 Scheduled Sending - Time not specified or invalid. Please enter a valid time.
TS-1072 Cannot send a scheduled message with a date or time in the past. Please check the date and time again.

Checking SMS Status


Verification of authorization code could be made by POST request to API with two parameters, recipient mobile phone number

								
turkeysms.com.tr/api/v3/sms-durumu/sms_durumu.php?api_key=API_KEY_HERE&sms_id=SMS_ID_HERE&response_type=php
								
							

The variables sent through the link are

								
$api_key  = '';
$sms_id	  = '';
$response_type = '';
								
							

Parameter Description

api_key$ varchar Your API key on your account will be placed here
sms_id$ int Message ID
response_type$ int Response is sending JSON or PHP

Call Back Reports

Example Response

								
Array
(
	[result] => true
	[sender_id] => SenderID
	[date_of_sending] => 2021-01-01
	[time_of_sending] => 13:10:00
	[sms_status] => Number received the message
	[sms_status_code] => TS-1024
	[sms_balance] => 1 SMS
	[operator] => Turkcell
)
								
							

Parameter Description

result The result of the operation, if successful, appears true, and if the transmission fails, it appears false
sender_id Message ID. Length of this parameter in each request may vary
date_of_sending The date the message was sent
time_of_sending The time the message was sent
sms_status Message Status - Delivered - Not delivered - Number out of coverage
sms_status_code Status Code
sms_balance Number of used credits
operator The name of the company to which the number belongs

Check Balance [POST]


You can inquire about the available balance in your account, both local and international.

				
turkeysms.com.tr/api/v3/bakiye_sorgulama/add-content
				
							

Variables sent for the inquiry:

				
$api_key  = '';
$response_type = '';
				
							

Explanation of the variables sent through the link:

api_key$ varchar Your API key placed here.
response_type$ int Option to display the server response in a specific programming language.

After the inquiry process, the server will respond with the following:

Example response from the server:


Array
(
	[result] => true
	[result_code] => TS-1040
	[result_message] => operation_success
	[api_key] => api_key
	[local_balance_sms] => 1
	[international_balance_tl] => 1
)
				

Explanation of the variables sent from the server:

result The result of the process. "true" indicates success, "false" indicates failure.
result_code The process code.
result_message The content of the operation message.
api_key Here appears the connection key for the account.
local_balance_sms Local balance - Inside Turkey, displayed as the number of messages.
international_balance_tl International balance - Displayed as a financial value in Turkish Lira.

International SMS


The term "international messages" refers to messages sent outside the borders of the Turkish Republic.
These messages include all numbers that do not start with the international code (+90-0090).
Turkey SMS service enables you to send SMS messages through your account to any country in the world. However, you need to charge your balance with an international account to send messages to any country.
The price of the message varies from one country to another, and the delivery time of the international message also varies. To send internationally, you must contact the Technical Support Center of Turkey SMS service to activate your account.

How do I send an international message through the API?

The process of sending an international message through the API is the same as sending a local message within Turkey, using the same link and all available options.
However, you must recharge your account with an international balance.
The recipient's number must be written in the international code.

Example


The text messaging system supports various programming languages for seamless integration. Below are examples for different programming languages:

PHP Java JavaScript NodeJS Python CSharp C(LibCURL) Go ObjectiveC Ruby Swift

PHP

function sendRequest($site, $data)
{
    $json = json_encode($data);
    $ch = curl_init($site);
    $header = array('Content-Type: application/json');
    curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
    $result = curl_exec($ch);
    curl_close($ch);
    return $result;
}
$api_key  = '';
$title    = '';
$text	  = '';
$sentto	  = '';

$body = array("api_key" => $api_key, "title"=>$title, "text"=>$text,"sentto"=>$sentto);
$result = sendRequest('turkeysms.com.tr/api/v3/gonder/add-content', $body);
//http://www.lalit.org/lab/convert-xml-to-array-in-php-xml2array/

JAVA

Unirest.setTimeouts(0, 0);
HttpResponse response = Unirest.post("turkeysms.com.tr/api/v3/gonder/add-content")
.header("Content-Type", "application/json")
.body("{\"api_key\":\"API_KEY_HERE\",\"title\":\"SMS_TITLE_HERE\",\"text\":\"TEXT_SMS\",\"sentto\":\"90500000000\"}")
.asString();

JavaScript

var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({"api_key":"API_KEY_HERE","title":"SMS_TITLE_HERE","text":"TEXT_SMS","sentto":"90500000000"});

var requestOptions = {
method: 'POST',
headers: myHeaders,
body: raw,
redirect: 'follow'
};

fetch("turkeysms.com.tr/api/v3/gonder/add-content", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));

Python

import requests

url = "turkeysms.com.tr/api/v3/gonder/add-content"

payload = "{\"api_key\":\"API_KEY_HERE\",\"title\":\"SMS_TITLE_HERE\",\"text\":\"TEXT_SMS\",\"sentto\":\"90500000000\"}"
headers = {
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data = payload)

print(response.text.encode('utf8'))

Ruby

require "uri"
require "net/http"

url = URI("turkeysms.com.tr/api/v3/gonder/add-content")

https = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request.body = "{\"api_key\":\"API_KEY_HERE\",\"title\":\"SMS_TITLE_HERE\",\"text\":\"TEXT_SMS\",\"sentto\":\"90500000000\"}"

response = https.request(request)
puts response.read_body

CSharp

var client = new RestClient("turkeysms.com.tr/api/v3/gonder/add-content");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\"api_key\":\"API_KEY_HERE\",\"title\":\"SMS_TITLE_HERE\",\"text\":\"TEXT_SMS\",\"sentto\":\"90500000000\"}",  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

C(LibCURL)

CURL *curl;
CURLcode res;
curl = curl_easy_init();
if(curl) {
  curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "POST");
  curl_easy_setopt(curl, CURLOPT_URL, "turkeysms.com.tr/api/v3/gonder/add-content");
  curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
  curl_easy_setopt(curl, CURLOPT_DEFAULT_PROTOCOL, "https");
  struct curl_slist *headers = NULL;
  headers = curl_slist_append(headers, "Content-Type: application/json");
  curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
  const char *data = "{\"api_key\":\"API_KEY_HERE\",\"title\":\"SMS_TITLE_HERE\",\"text\":\"TEXT_SMS\",\"sentto\":\"90500000000\"}";
  curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data);
  res = curl_easy_perform(curl);
}
curl_easy_cleanup(curl);


NodeJS

var unirest = require('unirest');
var req = unirest('POST', 'turkeysms.com.tr/api/v3/gonder/add-content')
  .headers({
    'Content-Type': 'application/json'
  })
  .send(JSON.stringify({"api_key":"API_KEY_HERE","title":"SMS_TITLE_HERE","text":"TEXT_SMS","sentto":"90500000000"}))
  .end(function (res) { 
    if (res.error) throw new Error(res.error); 
    console.log(res.raw_body);
  });

ObjectiveC


#import  Foundation/Foundation.h>

dispatch_semaphore_t sema = dispatch_semaphore_create(0);

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"turkeysms.com.tr/api/v3/gonder/add-content"]
  cachePolicy:NSURLRequestUseProtocolCachePolicy
  timeoutInterval:10.0];
NSDictionary *headers = @{
  @"Content-Type": @"application/json"
};

[request setAllHTTPHeaderFields:headers];
NSData *postData = [[NSData alloc] initWithData:[@"{\"api_key\":\"API_KEY_HERE\",\"title\":\"SMS_TITLE_HERE\",\"text\":\"TEXT_SMS\",\"sentto\":\"90500000000\"}" dataUsingEncoding:NSUTF8StringEncoding]];
[request setHTTPBody:postData];

[request setHTTPMethod:@"POST"];

NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
  if (error) {
    NSLog(@"%@", error);
  } else {
    NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
    NSError *parseError = nil;
    NSDictionary *responseDictionary = [NSJSONSerialization JSONObjectWithData:data options:0 error:&parseError];
    NSLog(@"%@",responseDictionary);
    dispatch_semaphore_signal(sema);
  }
}];
[dataTask resume];
dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);

Go


package main
import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)
func main() {
  url := ""turkeysms.com.tr/api/v3/gonder/add-content"
  method := "POST"
  payload := strings.NewReader("{\"api_key\":\"API_KEY_HERE\",\"title\":\"SMS_TITLE_HERE\",\"text\":\"TEXT_SMS\",\"sentto\":\"90500000000\"}")
  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
  }
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  defer res.Body.Close()
  body, err := ioutil.ReadAll(res.Body)

  fmt.Println(string(body))
}

Swift

import Foundation

var semaphore = DispatchSemaphore (value: 0)

let parameters = "{\"api_key\":\"API_KEY_HERE\",\"title\":\"SMS_TITLE_HERE\",\"text\":\"TEXT_SMS\",\"sentto\":\"90500000000\"}"
let postData = parameters.data(using: .utf8)

var request = URLRequest(url: URL(string: "turkeysms.com.tr/api/v3/gonder/add-content")!,timeoutInterval: Double.infinity)
request.addValue("application/json", forHTTPHeaderField: "Content-Type")

request.httpMethod = "POST"
request.httpBody = postData

let task = URLSession.shared.dataTask(with: request) { data, response, error in 
  guard let data = data else {
    print(String(describing: error))
    return
  }
  print(String(data: data, encoding: .utf8)!)
  semaphore.signal()
}

task.resume()
semaphore.wait()

SMS Libraries


You can download ready-made files in the programming language you want for your use

PHP File