Telegram Message Sending

The following types of Telegram messages are supported:

• text only;

• text + link to follow.

Request Examples

TextText + link

{
   "login": "Login",
   "password": "Password",
   "useTimeDiff": true,
   "id": "superId",
   "scheduleInfo":
   {
      "timeBegin": "10:00",
      "timeEnd": "12:00",
      "weekdaysSchedule": "123"
   },
   "destAddr": "79211234567",
   "message":
   {
      "type": "TELEGRAM",
      "data":
      {
         "text": "Hello, world!",
         "serviceNumber": "0000",
         "ttl": 3600,
         "ttlUnit": "SECONDS"
      }
   }
}

Request Parameters

Parameter	Required	Data type	Description
login	yes	string	Partner’s name.
password	yes	string	Partner’s password for sending messages.
destAddr	yes	string	Subscriber’s phone number. More details It contains the country code, operator code and phone number. For the Russian Federation, the code can be 8, 7 or +7. Examples: 72101234567, +72101234567, 8-210-123-45-67, 82101234567.
useTimeDiff	no	boolean	Taking into account the time zone when starting messaging. More details If true, the message is sent to the subscriber according to the messaging schedule and his time zone. If false, the message is sent according to the messaging initiator schedule UTC+3 regardless of the message recipient time zone. Default value: false.
id	no	string	Unique identifier on the Partner’s side. More details This parameter is necessary for controlling repeated submissions and duplication (the control service is activated separately). The Partner can call the Service Provider (request to send a message) multiple times with the same ID. In this case, the message will be sent to the subscriber only once (on the first request). In response to the requests, the Service Provider will return the same message identifier in the Service Provider's system to the Partner (the same as for the first request). The Service Provider optionally returns this identifier to the Partner in the message delivery report if it is available.
scheduleInfo	no	object	Messaging schedule. More details If not specified, it is sent immediately upon receipt of the request.
scheduleInfo/ timeBegin	no	string	Start time. More details For example: 10:00.
scheduleInfo/ timeEnd	no	string	End time. More details For example: 21:00.
scheduleInfo/ weekdaysSchedule	no	string	Messaging days. More details Specified by numbers from 1 (Monday) to 7 (Sunday). For example: 12345. If there are no restrictions on days of the week, this parameter can be empty or not delivered in the request.
scheduleInfo/ deadline	no	string	End date of the messaging. More details Specify the end date for message sending. For example: 2024-05-10T16:29:30+0300.
message	yes	object	Parameters of a message being sent. More details It contains information about the message type and its content.
message/type	yes	enum	Message type. More details Specify the TELEGRAM value.
message/data	yes	object	Parameters of the data being sent. More details To send a text only, specify the text attribute. To send a text and a link specify the text and link attributes.
message/data/ text	yes	string	Message text. More details Character limit: no more than 1000. The text of the message can be in Cyrillic or Latin, and may contain emojis.
message/data/ link	no	string	Random URL, passed in the text of a Telegram message. More details Number of characters: no more than 256. If the link length exceeds the specified value, the message will be rejected with an error. The error text: "The value limit of the link parameter is exceeded in the message". If an empty parameter is passed, the message will be rejected with an error. The error text: "The message is missing a value for the link parameter".
message/data/ serviceNumber	no	string	Sender’s name from which the message is being sent. More details To send the message successfully, please double-check that the service name is correct.
message/data/ ttl	no	integer	Message lifetime. More details Acceptable range in seconds: from 30 to 86400. Note When ttl = 0 or the parameter is absent in the request, the value from the default settings is used, which is set during the integration setup separately for each client.
message/data/ ttlUnit	no	enum	Unit of measurement of the message delivery period. More details It is transmitted only with ttl. Possible values are: SECONDS; MINUTES (by default); HOURS.
extraParam	no	string	Additional parameters passed in the message. More details Parameters are passed as param1=value1,param2=value2, where param1 and param2 — parameter names, value1 and value2 — values. Example: the string place=abzakovo,name=guest house-3 The comma character cannot be included in the parameter name, but it can be included in its value — in this case it must be doubled. Example: coordinates=53.8085896,,58.6362112
registeredDelivery	no	integer	Requirement of delivery reports. More details Specify whether delivery reports are required to track statuses. Possible values are: 0 — statuses are not required; 1 — statuses are required (by default); 2 — only the Undelivered status is required.
notifyUrl	no	string	Hostname of the incoming API to obtain the delivery report. More details This parameter is optional in the request, but when sending you need to consider the following: if the parameter is specified, it cannot be empty; the notifyUrl string must be no more than 2048 characters. If any of the specified conditions are not met, an error will be generated and the request will not be executed.
cascadeChainLink	no	object	Cascading message parameters. More details See Cascading Message Sending.

Response

After sending a message the Service Provider returns a response synchronously.

Successful Telegram Sending

In case of successful sending the Service Provider returns the 200 OK HTTP-code.

Response exampleResponse parameters

{
    "mtNum": "7390612217"
    "id": "8770599"
}

Telegram Sending Errors

For results with errors, a response HTTP code will differ from 200 (see Error Codes).

Response exampleResponse parameters

{
    "error": {
        "code": 4,
        "description": "Invalid request"
    },
    "extendedDescription": "Telegram message is absent"
}

In this example, there is no text in the Telegram message, but only a link is transmitted, which is an error.

Error Codes

Code	Description	HTTP-code
1	Service is unavailable	503
2	Invalid IP-address	403
3	Too many connections	429
4	Invalid request	400
5	Invalid login	401
6	Invalid password	401
7	serviceNumber is not defined	400
8	destAddr is not correct	406
9	Message type is not correct	406
10	Prohibited sending duplicates	409
11	Invalid TTL	406
100	100	500

Telegram Delivery Statuses

To receive Telegram message statuses, you need to set up the Delivery Status Service.

Request Example

Description of parameters is given in the paragraph Delivery Report.

   {
      "mtNum": "107930572",
      "status": 9,
      "type": "TELEGRAM",
      "doneDate": "2024-05-05T10:20:35+0300",
      "submitDate": "2024-05-05T10:19:55+0300",
      "sourceAddr": "TG_NAME",
      "destAddr": "72101234567",
      "text": "Hello!",
      "partCount": "001",
      "errorCode": "0",
      "mccMnc": "25012",
      "trafficType": 0
   }

Delivery Error Codes

Delivery error codes for each message type are provided in the corresponding tab of the Description of Error Codes (parameter status=5) section.

Event Notification

Additional parameters are intended for transmitting accurate statistics in Telegram messages.

Request exampleDescription of the parameters

{
     "mtNum": "107930572",
     "status": 9,
     "type": "TELEGRAM",
     "doneDate": "2024-05-05T10:20:35+0300",
     "submitDate": "2024-05-05T10:19:55+0300",
     "sourceAddr": "TG_NAME",
     "destAddr": "72101234567",
     "text": "Hello!",
     "partCount": "001",
     "errorCode": "0",
     "mccMnc": "25012",
     "trafficType": 0,
     "eventType": "view",
     "eventDate": "2024-05-05T10:30:35+0300",
     "viewsCount": 2,
     "clicksCount": 0
}