SendFileByUpload#
For the SendFileByUpload method, we recommend to use the media.green-api.com host
The method is aimed for sending a file uploaded by form (form-data). The message will be added to the send queue, in the response you will receive a link to the downloaded file. The rate at which messages are sent from the queue is managed by Message sending delay parameter.
The link is valid for 15 days.
The link can be reused using the SendFileByUrl 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:
{{mediaUrl}}/waInstance{{idInstance}}/sendFileByUpload/{{apiTokenInstance}}
For mediaUrl
, idInstance
and apiTokenInstance
request parameters, refer to Before you start section.
Request parameters#
Parameter | Type | Mandatory | Description |
---|---|---|---|
chatId | string | Yes | Chat Id |
file | file | Yes | Outgoing file |
fileName | string | No | File name. Must contain 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. |
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.
Quoting messages
For the message quoting mechanism to work correctly, the system must know about the message that will be quoted. You can make sure that the message is available for quoting by requesting the journaling method getMessage, if the message is not in the system, then it is impossible to quote such a message.
-
To quote incoming messages, you must enable the setting
Receive notifications about incoming messages and files
. -
To quote outgoing messages sent from a phone, enable the setting
Receive notifications about messages sent from a phone
.
This way, the messages will get into the system and they can be quoted. You can set up the settings using the SetSettings method or through your personal account.
Response#
Response parameters#
Parameter | Type | Description |
---|---|---|
idMessage | string | Sent message Id |
urlFile | string | Link to file (link expires 15 days) |
Response body example#
{
"idMessage": "3EB0C767D097B7C7C030",
"urlFile": "https://sw-media-out.storage.yandexcloud.net/1101776123/c1aabd48-c1c2-49b1-8f2d-f575a41777be.jpg"
}
SendFileByUpload errors#
For a list of errors common to all methods, refer to Common errors section
HTTP code | Error ID | Description |
---|---|---|
200 | failed to upload file | Request body exceeded 100kb |
400 | failed to upload file | Missing chatId field / extra field present / Invalid messageId specified for quote / file missing / Invalid field type / Non-form-data used / Invalid number |
400 | Bad Request Validation failed | Validation error |
400 | file should not be empty | The user submitted an empty file. The uploaded file must not be empty |
413 | request entity too large | Exceeded file size limit (~99.9mb). Occurs when sending files in 1C processing (version 8.3.22.1923). Possible solution: Change 1C version. |
500 | Internal Server Error failed to upload file | Missing file field |
500 | Internal Server Error | The method specified for the request is invalid. Specify the method POST and try again |
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 body example#
Request examples
import requests
url = "{{mediaUrl}}/waInstance{{idInstance}}/sendFileByUpload/{{apiTokenInstance}}"
payload = {'chatId': '11001234567@c.us',
'caption': 'Описание'}
files = [
('file', ('window.jpg', open('C:/window.jpg','rb'),'image/jpeg'))
]
headers= {}
response = requests.post(url, data=payload, files=files)
print(response.text.encode('utf8'))
curl --location '{{mediaUrl}}/waInstance{{idInstance}}/sendFileByUpload/{{apiTokenInstance}}' \
--form 'chatId="12345678910@c.us"' \
--form 'file=@"/Users/you/files/file.jpeg"' \
--form 'fileName="file.jpg"'
var restTemplate = new RestTemplate();
var requestUrl = new StringBuilder();
requestUrl
.append({{mediaUrl}})
.append("/waInstance").append({{idInstance}})
.append("/sendFileByUpload/")
.append({{apiTokenInstance}});
var headers = new HttpHeaders();
headers.setContentType(MediaType.MULTIPART_FORM_DATA);
var form = new LinkedMultiValueMap<>();
form.add("chatId", "12345678910@c.us");
form.add("file", new FileSystemResource(new File("/Users/you/files/file.jpeg")));
form.add("fileName", file.jpg);
form.add("caption", "Описание");
form.add("quotedMessageId", "BAE5F4886F6F2D05");
var requestEntity = new HttpEntity<>(form, headers);
var response = restTemplate.exchange(requestUrl.toString(), HttpMethod.POST, requestEntity, String.class);
System.out.println(response);
var file = new File("/Users/user/Desktop/fileExample.jpeg");
var requestUrl = new StringBuilder();
requestUrl
.append({{mediaUrl}})
.append("/waInstance").append({{idInstance}})
.append("/sendFileByUpload/")
.append({{apiTokenInstance}});
var form = new HashMap<String, Object>();
form.put("chatId", dto.getChatId());
form.put("file", dto.getFile());
form.put("fileName", dto.getFileName());
form.put("caption", dto.getCaption());
form.put("quotedMessageId", dto.getQuotedMessageId());
var response = Unirest.post(requestUrl.toString())
.fields(form)
.asString();
System.out.println(response);
program sendFileByUpload;
{$APPTYPE CONSOLE}
uses
System.SysUtils,
System.Classes, System.Net.HttpClient, System.Net.Mime, System.Net.URLClient, System.Net.HttpClientComponent;
var
HttpClient: TNetHTTPClient;
Response: IHTTPResponse;
FormData: TMultipartFormData;
EndpointURL, MEDIA_URL, ID_INSTANCE, API_TOKEN_INSTANCE: string;
begin
MEDIA_URL := 'https://media.green-api.com';
ID_INSTANCE := '110100001';
API_TOKEN_INSTANCE := 'd75b3a66374942c5b3c019c698abc2067e151558acbd451234';
EndpointURL := MEDIA_URL +'/waInstance' + ID_INSTANCE + '/sendFileByUpload/' + API_TOKEN_INSTANCE;
HttpClient := TNetHTTPClient.Create(nil);
FormData := TMultipartFormData.Create();
FormData.AddField('chatId', '71234567890@c.us');
FormData.AddField('caption', 'test');
FormData.AddFile('file', 'C:\tmp\bp.png');
try
Response := HTTPClient.Post(EndpointURL, FormData, nil);
if Response.StatusCode = 200 then
Writeln('[Response]: ' + Response.ContentAsString)
else
Writeln('[ERROR ' + IntToStr(Response.StatusCode) + ']:' + Response.StatusText + '' + Response.ContentAsString);
readln;
except
on E: Exception do
Writeln(E.ClassName, ': ', E.Message);
end;
HttpClient.Free;
FormData.Free;
end.