Summary

When you send a file through an active WhatsApp session using the Wati API, the attachment name may appear as null or untitled if you don't include the caption parameter in your request.

To fix this, include the caption parameter as a query parameter and set it to the file name you want to display. This article explains how to apply this fix using the legacy v1 API and provides guidance for the recommended v3 API.

Instructions

1. Fix the Attachment Name

The caption parameter specifies the name displayed for the file attachment. If you omit this parameter, the attachment name may appear as null or untitled.

To display the correct file name, include caption in your API request as a query parameter.

Important: Pass caption in the query string, not in the request body. Send the file itself as a multipart form field named file.

2. Fix the Issue Using the Legacy v1 API

You can use the legacy v1 endpoint to send a file during an active WhatsApp session.

Endpoint:

POST https://live-mt-server.wati.io/{tenantId}/api/v1/sendSessionFile/{target}

API Parameters

Parameter	Type	Location	Description
`tenantId`	String	Path	Your Wati tenant ID.
`target`	String	Path	The recipient's phone number, Contact ID, or Business-Scoped User ID (BSUID).
`caption`	String	Query parameter	The file name to display for the attachment.
`file`	File	Multipart request body	The file you want to send. Use `file` as the form field name.

Example Request

The following example sends a file named Invoice_October.pdf and uses that name as the attachment caption.

curl --location 'https://live-mt-server.wati.io/{tenantId}/api/v1/sendSessionFile/85264318722?caption=Invoice_October.pdf' \
--header 'Authorization: Bearer <Token>' \
--form 'file=@"/path/to/Invoice_October.pdf"'

Replace the following placeholders with your actual values:

{tenantId} — Your Wati tenant ID.
85264318722 — The recipient's phone number.
<Token> — Your Wati API access token.
/path/to/Invoice_October.pdf — The path to the file you want to upload.

You can change Invoice_October.pdf to the attachment name you want to display.

3. Use the Recommended v3 API

For new integrations, use the v3 API where supported.

Endpoint:

POST https://live-mt-server.wati.io/api/ext/v3/conversations/messages/file

Unlike legacy v1 endpoints, v3 endpoint paths do not include /{tenantId}/.

Create a scoped API token in your Wati account under Connector > API > Create API Token.

The target field also supports the Channel:PhoneNumber format.

Refer to the Wati developer documentation for the v3 endpoint's required parameters and request format.

4. Important Notes

Include the caption: Pass the caption parameter as a query parameter to specify the attachment name.
Use the correct file field: Upload the file as a multipart form field named file.
Check the API response correctly: An HTTP 200 response means the request was accepted; it does not confirm that the file was delivered to the recipient.
Track delivery: Use the sentMessageDELIVERED_v2 webhook event to confirm message delivery.

Following these guidelines helps prevent file attachment names from appearing as null or untitled when sending files through the Wati API.

How to fix file attachment names appearing as null or untitled