SendFileByUrl#
The method is aimed for sending a file uploaded by Url. The message will be added to the send queue. The message will be kept for 24 hours in the queue and will be sent immediately after phone authorization. The rate at which messages are sent from the queue is managed by Message sending delay parameter.
To form a link for your file you can use external storages.
We recommend using our external file storage via the UploadFile method.
Video, audio and image files available for viewing and listening to are sent as in native-mode WhatsApp. Documents are sent in the same way as in native-mode WhatsApp. Outgoing file type and send method is determined by the file extension. Description is only added to images and video.
The maximum size of outgoing files is 100 MB.
Sending multiple files with one request is not possible. 1 file is sent with only 1 message. The ability to send multiple files at the same time is created only on the side of the WhatsApp application.
There are no restrictions on image resolutions. However, when sending images through the API with a resolution exceeding 3000x3000 pixels, thumbnails will not be generated.
List of file extensions, that could be successfully sent and received via the API
Request#
To send a file, you have to execute a request at:
{{apiUrl}}/waInstance{{idInstance}}/sendFileByUrl/{{apiTokenInstance}}
For apiUrl
, idInstance
and apiTokenInstance
request parameters, refer to Before you start section.
Request parameters#
Parameter | Type | Mandatory | Description |
---|---|---|---|
chatId | string | Yes | Chat Id |
urlFile | string | Yes | Link to outgoing file |
fileName | string | Yes | File name. Must contain the file extension. Requires UTF-8 encoding without BOM. For example: test.jpg |
caption | string | No | File caption. Caption added to video, images. The maximum field length is 20000 characters. |
quotedMessageId | string | No | Quoted message Id. If present, the message will be sent quoting the specified chat message. Quoting a message is only possible from the same chat to which it is sent. To send messages from another chat, use the ForwardMessages method |
Note
-
Link format recommendations
- Symbols a-z, A-Z, 0-9, - (hyphen), _ (underscore) can be used in the link
- The link must not contain special characters ~$€%#£?! and spaces
- UTF-8 link character encoding without BOM
- It is required to transfer non-encoded links (the system encodes the link itself)
- It is required that the link points to a specific file, and not to the html page link examples
- Required to use fast storage, no limit on the number of file requests
-
Field fileName
It is required to specify the fileName field with the correct file extension.
File type detection by the system:
- By the extension specified in the file name, in the fileName field
- If the fileName field does not contain an extension, then the file type is obtained by Content-Type from the link header
- If the Content-Type field in the header is missing or contains a non-existent file type, the system will try to determine the file type based on the bytes of the file
- If the system cannot determine the file type, it will be sent with the default type (binary file)
Time to send a file
Sending files occurs in several stages:
- Receive the file
- Uploading a file to the WhatsApp server
- Request to send a file to WhatsApp
The time to send a file depends on the file size, the speed of receiving the file and WhatsApp processing the file. Depending on these factors, the time to send a file can vary from 1 to 20 seconds.
Request body example#
Sending a message to a personal chat:
{
"chatId": "11001234567@c.us",
"urlFile": "https://my.site.com/img/horse.png",
"fileName": "horse.png",
"caption": "Little horse"
}
Sending a message to a group chat:
{
"chatId": "11001234567-1581234048@g.us",
"urlFile": "https://my.site.com/img/horse.png",
"fileName": "horse.png",
"caption": "Little horse"
}
Sending a quoted message:
{
"chatId": "11001234567@с.us",
"urlFile": "https://my.site.com/img/horse.png",
"fileName": "horse.png",
"caption": "Little horse",
"quotedMessageId": "361B0E63F2FDF95903B6A9C9A102F34B"
}
Response#
Response parameters#
Parameter | Type | Description |
---|---|---|
idMessage | string | Outgoing message Id |
Response body example#
{
"idMessage": "3EB0C767D097B7C7C030"
}
SendFileByUrl errors#
For a list of errors common to all methods, refer to Common errors section
HTTP code | Error ID | Description |
---|---|---|
400 | Bad Request Validation failed | Validation error |
400 | Validation failed. Details: url has incorrect format. It should start with http(s):// | Incorrect URL |
500 | request entity too large | Exceeding the allowed json length (>100kb) |
Sending with invalid Quoted message ID
If the quotedMessageId
is specified incorrectly, the system will return code 200 and the id of the message, but it will not be delivered to the recipient.
Request examples#
import requests
url = "{{apiUrl}}/waInstance{{idInstance}}/sendFileByUrl/{{apiTokenInstance}}"
payload = {
"chatId": "11001234567@c.us",
"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": "12345678910@c.us",
"urlFile": "https://avatars.mds.yandex.net/get-pdb/477388/77f64197-87d2-42cf-9305-14f49c65f1da/s375",
"fileName": "horse.png",
"caption": "лошадка"
}'
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\": \"11001234567@c.us\",\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\": \"11001234567@c.us\",\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
' 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"":""90123456789@c.us"",""urlFile"":""https://my.site.com/img/horse.png"",""fileName"":""horse.png"",""caption"":""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