SendFileByUrl#

The method is intended for sending a file that is downloaded by a link.

The message is added to the sending queue.
The rate at which messages are sent from the queue is set by the message sending interval.

The method uses limits on the request rate per second.

The file storage period is 24 hours.

Request#

To send a file, you need to execute a request at:

POST

{{apiUrl}}/waInstance{{idInstance}}/sendFileByUrl/{{apiTokenInstance}}

To get the apiUrl, idInstance and apiTokenInstance request parameters, refer to the Before you start section.

Request parameters#

Parameter	Type	Required	Description
`chatId`	string	Yes	Chat identifier
`urlFile`	string	Yes	Link to the file being sent
`fileName`	string	Yes	File name. It must contain the file extension. You need to use UTF-8 encoding without BOM. For example: `test.jpg`
`caption`	string	No	Caption under the file. Maximum length - 1024 characters
`quotedMessageId`	string	No	Identifier of the quoted message
`typingTime`	integer	No	The time the typing notification is displayed in the correspondent's chat. Takes a value in the range from 1000 to 20000 milliseconds (from 1 to 20 seconds)
`typingType`	string	No	Typing type. Possible values:
			`text` - "typing..." (default)
			`record_voice_note` - "recording a voice message..."
			`upload_voice_note` - "sending a voice message..."
			`record_video_note` - "recording a video message..".
			`upload_video_note` - "sending a video message..."
			`record_video` - "recording a video..."
			`upload_video` - "sending a video..."
			`upload_photo` - "sending a photo..."
			`upload_document` - "sending a file..."
			`choose_sticker` - "choosing a sticker..."
			`choose_location` - "choosing a location..."
			`choose_contact` - "choosing a contact..."

Link format in urlFile

Recommendations on the link format:

The link may use the characters a-z, A-Z, 0-9, - (hyphen), _ (underscore)
The link must not contain the special characters ~$€%#£?! and spaces
The character encoding of the link is UTF-8 without BOM
You need to pass non-encoded links (the system encodes the link itself)
The link must point to a specific file, not to an html page
You need to use fast storage, without a limit on the number of file requests

File extension in fileName

The fileName field

You must specify the fileName field with the correct file extension.

How the system determines the file type:

By the extension specified in the file name, in the fileName field
If the fileName field does not contain an extension, the file type is obtained from the Content-Type in the link header
If the Content-Type field is missing in the header or contains a non-existent file type, the system will try to determine the file type by the bytes of the file
If the system cannot determine the file type, the file will be sent with the default type (a binary file)

Time to send a file

Files are sent in several stages:

Getting the file
A request to send the file to Telegram

The time to send a file depends on the file size, the file download speed and the processing of the file by Telegram. Depending on these factors, the time to send a file may vary from 1 to 20 seconds.

Request body example#

Sending a message to a personal chat#

{
    "chatId": "10000000",
    "urlFile": "https://avatars.mds.yandex.net/get-pdb/477388/77f6411da/s375",
    "fileName": "horse.png",
    "caption": "little horse"
}

Sending a message to a group chat#

{
    "chatId": "-10000000000000",
    "urlFile": "https://avatars.mds.yandex.net/get-pdb/477388/77f64191da/s375",
    "fileName": "horse.png",
    "caption": "little horse"
}

Sending a message with quoting#

{
    "chatId": "-10000000000000",
    "urlFile": "https://avatars.mds.yandex.net/get-pdb/477388/77f64191da/s375",
    "fileName": "horse.png",
    "caption": "little horse",
    "quotedMessageId": "1769676078000"
}

Response#

Response fields#

Field	Type	Description
`idMessage`	string	Identifier of the sent message

Response body example#

{
    "idMessage": "1769676078000"
}

Errors#

For the list of errors common to all methods, see the Common errors section

HTTP code	Error identifier	Description
400	`Bad Request` `Validation failed`	Validation error
400	`Validation failed.` `Details: url has incorrect format. It should start with http(s)://'`	Incorrect link

Code examples#

PythoncURLJava - SpringJava - UnirestVBA

import requests

url = "{{apiUrl}}/waInstance{{idInstance}}/sendFileByUrl/{{apiTokenInstance}}"

payload = {
    "chatId": "10000000", 
    "urlFile": "https://avatars.mds.yandex.net/get-pdb/477388/77f64197-87d2-42cf-9305-14f49c65f1da/s375", 
    "fileName": "horse.png", 
    "caption": "little horse"
}
headers = {
    'Content-Type': 'application/json'
}

response = requests.post(url, json=payload)

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

curl --location '{{apiUrl}}/waInstance{{idInstance}}/sendFileByUrl/{{apiTokenInstance}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "chatId": "10000000",
    "urlFile": "https://avatars.mds.yandex.net/get-pdb/477388/77f64197-87d2-42cf-9305-14f49c65f1da/s375",
    "fileName": "horse.png",
    "caption": "little horse"
}'

var restTemplate = new RestTemplate();
var requestUrl = new StringBuilder();
requestUrl
    .append({{apiUrl}})
    .append("/waInstance").append({{idInstance}})
    .append("/sendFileByUrl/")
    .append({{apiTokenInstance}});

var headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_JSON);

var jsonBody = "{\r\n   \t\"chatId\": \"10000000\",\r\n\t\"urlFile\": \"https://avatars.mds.yandex.net/get-pdb/477388/77f64197-87d2-42cf-9305-14f49c65f1da/s375\",\r\n\t\"fileName\": \"horse.png\",\r\n\t\"caption\": \"little horse\"\r\n}";

var requestEntity = new HttpEntity<>(jsonBody, headers);

var response = restTemplate.exchange(requestUrl.toString(), HttpMethod.POST, requestEntity, String.class);
System.out.println(response);

var requestUrl = new StringBuilder();
requestUrl
    .append({{apiUrl}})
    .append("/waInstance").append({{idInstance}})
    .append("/sendFileByUrl/")
    .append({{apiTokenInstance}});

var response = Unirest.post(requestUrl.toString())
    .header("Content-Type", "application/json")
    .body("{\r\n   \t\"chatId\": \"10000000\",\r\n\t\"urlFile\": \"https://avatars.mds.yandex.net/get-pdb/477388/77f64197-87d2-42cf-9305-14f49c65f1da/s375\",\r\n\t\"fileName\": \"horse.png\",\r\n\t\"caption\": \"little horse\"\r\n}")
    .asString();

System.out.println(response);

Sub SendFileByUrl()
    Dim url As String
    Dim RequestBody As String
    Dim http As Object
    Dim response As String

    ' The apiUrl, idInstance and apiTokenInstance values are available in console, double brackets must be removed
    url = "{{apiUrl}}/waInstance{{idInstance}}/SendFileByUrl/{{apiTokenInstance}}"

    ' chatId is the number to send the message (@c.us for private chats, @g.us for group chats), urlFile - url link, fileName - file name with extension, caption - title
    RequestBody = "{""chatId"":""10000000"",""urlFile"":""https://my.site.com/img/horse.png"",""fileName"":""horse.png"",""caption"":""Little horse""}"

    Set http = CreateObject("MSXML2.XMLHTTP")

    With http
        .Open "POST", url, False
        .setRequestHeader "Content-Type", "application/json"
        .Send RequestBody
    End With

    response = http.responseText

    Debug.Print response

    ' Outputting the answer to the desired cell
    ' Range("A1").Value = response

    Set http = Nothing
End Sub