To send a new Telegram message you need to send POST request to the following URL
https://api.smartsender.io/v3/telegram/send
Request body
{
"botId": "YOUR_TELEGRAM_BOT_ID",
"contact": "user@example.com",
"content": [
{
"type": "text",
"text": "TELEGRAM_CONTENT_TEXT",
"buttons": [
{
"text": "Title of button",
"link": "FINAL_DESTINATION_URL"
}
]
},
{
"type": "file",
"file": "ICON_file_URL"
},
{
"type": "image",
"image": "ICON_IMAGE_URL"
}
],
"tags": [
"tag1",
"tag2"
]
}
| Parameters |
botId
'required' |
Unique Telegram botId that is already registered |
contact
'required' |
The ’email’ address,‘userId’ or ‘phoneNumber’ of the recipient stored in the corresponding contactList. |
content
'required' |
Telegram message content that you want to send. You have several types of blocks for creating messages. |
type text
‘optional’ |
text
'required' |
Telegram content text you want to send.
'required' |
buttons
‘optional’
Important: Using a button without text block is not possible |
text
'required' |
Text for button name |
link
'required' |
Link to the page where subscribers will get when they click on the link |
type file
‘optional’ |
You can attach a file for you message |
file
'required' |
Link to the file will be downloaded by subscribers when they click on the link. |
type image
‘optional’ |
Shows image in a telegram message |
image
'required' |
Link to the image will be shown to subscribers when the message is delivered |
tags
‘optional’ |
An array of string to tag the message with. Stats are accumulated using tags, though we only store the first 100 we see, so this should not be unique or changed frequently. Tags should be 50 characters or less.
WARNING: Any tags starting with an underscore are reserved for internal use and will cause errors. |
Response:
{
"result":true,
"telegram_message_ids":["5d914c3dd132d5f45a4e3670"]
}
| Return Value the sending results for a single recipient |
| telegram_message_ids |
The message unique identification number in SmartSender system. With this ID number
you can get all the statistics on each sent message. |
| result |
The sending status of the recipient: |
| true |
The message is accepted and queued |
| false |
The message is rejected |
Example Error Response JSON:
{
"result":false,
"errors":[
"Error description text"
]
}
Errors.
The reason for the rejection. |
| result |
The sending status of the message. |
| true |
The message is accepted and queued |
| false |
The message is rejected |
| Error description |
“Argument botId must be a non-empty string” |
| “Argument contact must be a non-empty string filled with valid email, phoneNumber or userId” |
| “Argument content must be an array” |
| “Argument content must be a non-empty array” |
| “Argument type in template row {templateRowNum} must be present” |
| “Unknown type {type} in template row {templateRowNum}” |
| “Argument text must be present in template row {templateRowNum}” |
| “Argument text must be non-empty in template row {templateRowNum}” |
| “Argument text can be {limit} characters length” |
| “Argument button text must be present in template row {templateRowNum}, button number {buttonNum}” |
| “Argument button text must be non-empty in template row {templateRowNum}, button number {buttonNum}” |
| “Argument button link must be present in template row {templateRowNum}, button number {buttonNum}” |
| “Argument button link must be non-empty in template row {templateRowNum}, button number {buttonNum}” |
| “Argument button link must be a valid link in template row {templateRowNum}, button number {buttonNum}” |
| “Argument button link must be a valid HTTP\/HTTPS link in template row {templateRowNum}, button number {buttonNum}” |
| “Argument image must be present in template row {templateRowNum}” |
| “Argument image must be non-empty in template row {templateRowNum}” |
| “Argument image must be a valid image url in template row {templateRowNum}” |
| “Argument image must be a valid image url over HTTPS in template row {templateRowNum}” |
| “Argument file must be present in template row {templateRowNum}” |
| “Argument file must be non-empty in template row {templateRowNum}” |
| “Argument file must be a valid image url in template row {templateRowNum}” |
| “Argument file must be a valid image url over HTTPS in template row {templateRowNum}” |
| “Argument tags must be an array of strings” |
| “Tag name must be a non-empty string” |
| “Tags should be 50 characters or less” |
| “Any tags starting with an underscore are reserved for internal use and will cause errors” |
| “Bot {botId} doest not have contact list” |
| “Argument botId must be a non-empty string” |
| “Argument contact must be a non-empty string filled with valid email, phoneNumber or userId” |
| “Argument content must be an array” |
| “Argument content must be a non-empty array” |
| “Argument type in template row {templateRowNum} must be present” |
| “Unknown type {type} in template row {templateRowNum}” |
| “Argument text must be present in template row {templateRowNum}” |
| “Argument text must be non-empty in template row {templateRowNum}” |
| “Argument text can be {limit} characters length” |
| “Argument button text must be present in template row {templateRowNum}, button number {buttonNum}” |
| “Argument button text must be non-empty in template row {templateRowNum}, button number {buttonNum}” |
| “Argument button link must be present in template row {templateRowNum}, button number {buttonNum}” |
| “Argument button link must be non-empty in template row {templateRowNum}, button number {buttonNum}” |
| “Argument button link must be a valid link in template row {templateRowNum}, button number {buttonNum}” |
| “Argument button link must be a valid HTTP\/HTTPS link in template row {templateRowNum}, button number {buttonNum}” |
| “Argument image must be present in template row {templateRowNum}” |
| “Argument image must be non-empty in template row {templateRowNum}” |
| “Argument image must be a valid image url in template row {templateRowNum}” |
| “Argument image must be a valid image url over HTTPS in template row {templateRowNum}” |
| “Argument file must be present in template row {templateRowNum}” |
| “Argument file must be non-empty in template row {templateRowNum}” |
| “Argument file must be a valid image url in template row {templateRowNum}” |
| “Argument file must be a valid image url over HTTPS in template row {templateRowNum}” |
| “Telegram not allowed for your account” |
| “Telegram bot {bot} not found” |
| “Contact with {contact} not found” |
| “Contact {contact} is not subscribed to bot” |
| “Contact {contact} is not subscribed to telegram channel” |
| “Payment required” |
| “Invalid authorization token!” |
| “Internal server error” |
| “Bad Request” |
| “no matches found for access token {accessToken}” |
| “user {id} not enabled” |
| “no data found for key {userId}” |
| “access token check failed for key\/secret $key\/$accessToken” |
| “Argument {argument} required” |
PHP Example:
$accessToken = "YOUR_API_KEY";
$url = 'https://api.smartsender.io/v3/telegram/send';
$body = json_encode([
"botId" => "YOUR_TELEGRAM_BOT_ID",
"contact" => "user@example.com",
"content" => [
[
"type" => "text",
"text" => "TELEGRAM_CONTENT_TEXT",
"buttons" => [
[
"text" => "Title of button_first",
"link" => "FINAL_DESTINATION_URL",
],
[
"text" => "Title of button_second",
"link" => "FINAL_DESTINATION_URL",
],
],
],
[
"type" => "file",
"file" => "ICON_file_URL_FIRST",
],
[
"type" => "file",
"file" => "ICON_file_URL_SECOND",
],
[
"type" => "image",
"image" => "ICON_IMAGE_URL_FIRST",
],
[
"type" => "image",
"image" => "ICON_IMAGE_URL_SECOND",
],
],
"tags" => [
"TelegramTag1",
"TelegramTag2",
],
]);
/**
* Request Example
*/
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Access-Token: $accessToken",
'Content-Type: application/json',
'Content-Length: ' . strlen($body),
]);
$result = curl_exec($ch);
if ($result === false) {
echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
echo strval($result) . PHP_EOL;
}
curl_close($ch);
