Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Send and Receive Media Messages with WhatsApp in Java Servlets


(warning)

Warning

Twilio is launching a new Console. Some screenshots on this page may show the Legacy Console and therefore may no longer be accurate. We are working to update all screenshots to reflect the new Console experience. Learn more about the new Console(link takes you to an external page).

In this tutorial, we'll set up a Java Servlets application that uses the WhatsApp Channel to:

  • Send media messages
  • Reply to incoming messages with media

The code samples in this tutorial use Twilio's Java helper library(link takes you to an external page), Java, and Servlets.


Send outbound media messages through WhatsApp

send-outbound-media-messages-through-whatsapp page anchor

Just like when sending an MMS, sending an outbound WhatsApp message uses Twilio's Message resource. This section walks you through the setting up and sending media in a WhatsApp message. Media can consist of images, audio files, and PDFs.

Sign up for (or log in to) your Twilio Account and activate the Sandbox

sign-up-for-or-log-in-to-your-twilio-account-and-activate-the-sandbox page anchor

Before you can send a WhatsApp message from your web language, you'll need to sign up for a Twilio account(link takes you to an external page) or sign into your existing account and activate the Twilio Sandbox for WhatsApp(link takes you to an external page). The Sandbox allows you to prototype with WhatsApp immediately using a shared phone number without waiting for your Twilio number to be approved by WhatsApp.

To get started, select a number from the available sandbox numbers to activate your sandbox.

WA_Sandbox.

Be sure to take note of the phone number you choose in the Sandbox. You will need this later when we're ready to send some messages.

Gather your Twilio account information

gather-your-twilio-account-information page anchor

Before you can send any messages, you'll need to gather your Twilio account credentials. You can find these in the Twilio Console(link takes you to an external page).

  • Account SID - Used to identify yourself in API requests
  • Auth Token - Used to authenticate REST API requests
Account Credentials.

For all of our code snippets and Java examples, you need to authenticate with the Account SID and Auth Token.

(error)

Danger

This tutorial uses hard-coded credentials at the top of the code; you should follow best practices regarding credential protection in production.

Send a media WhatsApp message via the REST API

send-a-media-whatsapp-message-via-the-rest-api page anchor

To send an outgoing media message via WhatsApp from your Twilio account you'll need to make an HTTP POST to Twilio's Message resource.

Sending a media message through WhatsApp is similar to sending a text-based message over WhatsApp with one important addition: the media_url parameter. The media_url parameter in this code tells Twilio where to retrieve the media that we want to include in the WhatsApp message. (You can prevent unauthorized access to your media(link takes you to an external page) by turning on HTTP Basic Auth for media URLs in the Twilio Console(link takes you to an external page).)

(warning)

Warning

If you joined your Sandbox more than 24 hours ago, you will need to send a fresh inbound message to your WhatsApp number in order to then send yourself a media message. WhatsApp currently does not support media in "template" messages that take place outside of a 24-hour "session".

Twilio's Node helper library helps you to create a new instance of the Message resource. When you do this, you'll specify the to, from, and mediaUrl parameters of your message.

If you don't already have the Java helper library installed you can add it to your POM dependencies by looking up the latest version here(link takes you to an external page):

Now, create a file named app``.java and include the following code:

Send a media message with WhatsApp

send-a-media-message-with-whatsapp page anchor
Java

_27
// Install the Java helper library from twilio.com/docs/java/install
_27
_27
import java.net.URI;
_27
import com.twilio.type.PhoneNumber;
_27
import java.util.Arrays;
_27
import com.twilio.Twilio;
_27
import com.twilio.rest.api.v2010.account.Message;
_27
_27
public class Example {
_27
// Find your Account SID and Auth Token at twilio.com/console
_27
// and set the environment variables. See http://twil.io/secure
_27
public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID");
_27
public static final String AUTH_TOKEN = System.getenv("TWILIO_AUTH_TOKEN");
_27
_27
public static void main(String[] args) {
_27
Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
_27
Message message =
_27
Message.creator(
_27
new com.twilio.type.PhoneNumber("whatsapp:+14155238886"),
_27
new com.twilio.type.PhoneNumber("whatsapp:+15017122661"),
_27
Arrays.asList(URI.create(
_27
"https://images.unsplash.com/photo-1545093149-618ce3bcf49d?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=668&q=80")))
_27
.create();
_27
_27
System.out.println(message.getSid());
_27
}
_27
}

Output

_28
{
_28
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_28
"api_version": "2010-04-01",
_28
"body": "Hello! 👍",
_28
"date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
_28
"date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
_28
"date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
_28
"direction": "outbound-api",
_28
"error_code": null,
_28
"error_message": null,
_28
"from": "whatsapp:+15017122661",
_28
"num_media": "0",
_28
"num_segments": "1",
_28
"price": null,
_28
"price_unit": null,
_28
"messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_28
"sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_28
"status": "queued",
_28
"subresource_uris": {
_28
"media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
_28
},
_28
"tags": {
_28
"campaign_name": "Spring Sale 2022",
_28
"message_type": "cart_abandoned"
_28
},
_28
"to": "whatsapp:+14155238886",
_28
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
_28
}

Replace the placeholder values for accountSid and authToken with your unique values. You can find these in your Twilio console(link takes you to an external page).

(error)

Danger

Please note: it's okay to hardcode your credentials when getting started, but you should use environment variables to keep them secret before deploying to production. Check out how to keep your Twilio credentials secure.

The to number should be the phone number for the destination WhatsApp account in the E.164 format. If you are using the WhatsApp Sandbox, you can only send messages to numbers that have joined the Sandbox.

You'll tell Twilio which phone number to use to send this message by replacing the from number with the whatsapp: channel identifier followed by the Sandbox number in E.164 format.

Save the file and run it:


_10
mvn compile exec:java -Dexec.mainClass=com.twilio.app.App

In a few moments, you should receive a WhatsApp message with an image!

Please note that WhatsApp does not support including a text body in the same message as a video, audio file, document, contact (vCard), or location. If you pass the Body parameter on a message with one of these media types, the body will be ignored and not delivered to the device.

Understanding Twilio's Response

understanding-twilios-response page anchor

When you send an outbound WhatsApp media message, Twilio sends data about the message in its response to your request. The JSON response contains the unique SID and URI for your media resource:


_10
"subresource_uris": {"media": "/2010-04 01/Accounts/ACxxxxxxxx/Messages/SMxxxxxxxxxxxxx/Media.json"}

When the Twilio REST API creates your new Message resource, it saves the image found at the specified mediaUrl as a Media resource. Once created, you can access this resource at any time via the API.

You can print this value from your C# code to see where the image is stored. The following line to the end of your program.cs file prints out your newly provisioned Media URI:


_10
System.out.println(message.subresourceUris.get("media");


Respond with media in WhatsApp

respond-with-media-in-whatsapp page anchor

To reply using media to incoming WhatsApp messages, you'll need to provide Twilio with a webhook URL that points to a server that runs code to inspect and save the media files.

(warning)

Warning

WhatsApp media content is currently only supported in Session Messages. If the WhatsApp session with a user expires, you must wait for an inbound message to create a new session before you can send them a media message.

Webhooks are user-defined HTTP(link takes you to an external page) callbacks. They are usually triggered by some event, such as receiving an SMS message or an incoming phone call. When that event occurs, Twilio makes an HTTP request (usually a POST or a GET(link takes you to an external page)) to the URL configured for the webhook.

To handle a webhook, you only need to build a small web application that can accept the HTTP requests. Almost all server-side programming languages offer some framework for you to do this. In this tutorial, we'll be setting up our web application with Servlets.

Webhook functionality is the same for every Twilio application. First, a webhook makes an HTTP request to a URI that you provide to Twilio. When it receives this request, your application performs pre-defined logic. This could be something like database read/writes or calling another API. Finally, your application sends a TwiML response to Twilio in which it specifies the instructions for Twilio to follow.

TwiML is the Twilio Markup Language, which is just to say that it's an XML(link takes you to an external page) document with special tags defined by Twilio to help you build your messaging and voice applications.

TwiML is easier shown than explained:


_10
<?xml version="1.0" encoding="UTF-8"?>
_10
<Response>
_10
<Message>Thanks for the message!</Message>
_10
</Response>

Every TwiML document has the <Response> element, which can contain one or more verbs. Verbs are actions you'd like Twilio to take, such as <Say> a greeting to a caller, or send an SMS <Message> in reply to an incoming message. For a full reference on everything you can do with TwiML, refer to our TwiML API Reference.

To send back a media in your WhatsApp reply, you need to include the media TwiML element with the URL to the media file. One media attachment is supported per message, with a size limit of 5MB.

Generate TwiML in your application

generate-twiml-in-your-application page anchor

To reply to an incoming WhatsApp message, you can either write raw TwiML or use a helper library. When you use the helper library, you don't have to worry about generating the raw XML yourself.

Reply with media to incoming WhatsApp messages

reply-with-media-to-incoming-whatsapp-messages page anchor

_42
package com.twilio.whatsapp_media.servlet;
_42
_42
import java.io.IOException;
_42
import java.io.PrintWriter;
_42
_42
import javax.servlet.annotation.WebServlet;
_42
import javax.servlet.http.HttpServlet;
_42
import javax.servlet.http.HttpServletRequest;
_42
import javax.servlet.http.HttpServletResponse;
_42
_42
import com.twilio.twiml.MessagingResponse;
_42
import com.twilio.twiml.messaging.Body;
_42
import com.twilio.twiml.messaging.Media;
_42
import com.twilio.twiml.messaging.Message;
_42
_42
@WebServlet(urlPatterns = { "/" })
_42
public class WhatsappMediaWebhook extends HttpServlet {
_42
private static final String GOOD_BOY_URL = "https://images.unsplash.com/photo-1518717758536-85ae29035b6d?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1350&q=80";
_42
_42
@Override
_42
protected void doPost(HttpServletRequest request, HttpServletResponse response)
_42
throws IOException {
_42
var numMedia = Integer.parseInt(request.getParameter("NumMedia"));
_42
var twimlResponse = new MessagingResponse.Builder();
_42
if (numMedia > 0) {
_42
twimlResponse.message(
_42
new Message.Builder().body(new Body.Builder("Thanks for the image! Here's one for you!").build())
_42
.media(new Media.Builder(GOOD_BOY_URL).build()).build());
_42
} else {
_42
twimlResponse.message(new Message.Builder().body(new Body.Builder("Send us an image!").build()).build());
_42
}
_42
_42
response.setContentType("text/xml");
_42
response.setCharacterEncoding("UTF-8");
_42
PrintWriter out = response.getWriter();
_42
out.write(twimlResponse.build().toXml());
_42
_42
out.flush();
_42
out.close();
_42
}
_42
_42
}

You have the code - now you need a URL you can give to Twilio.

Twilio can only access public servers on the Internet. That means you need to take your web application and publish it to a web or cloud hosting provider (of which there are many(link takes you to an external page)), you can host it on your own server, or you can use a service such as ngrok(link takes you to an external page) to expose your local development machine to the internet. (We only recommend the latter for development and testing purposes and not for production deployments.)

To send media in response to an incoming WhatsApp message, simply add an image URL. If necessary, restart your server, then send a message to your WhatsApp number again. You should receive a WhatsApp message that includes an image. Check out the API Reference for more details.

Configure your webhook URL

configure-your-webhook-url page anchor

Now that you have a URL for your web application's TwiML reply generating routine, you can configure your Twilio phone number to call your webhook URL whenever a new WhatsApp message comes in for you.

You can set the webhook URL for incoming messages to your server in the Sandbox(link takes you to an external page).

Make sure you choose HTTP POST or HTTP GET to correspond to what your web application is expecting. Usually, the default of POST is fine.

(warning)

Warning

Twilio supports HTTP Basic and Digest Authentication. Authentication allows you to password protect your TwiML URLs on your web server so that only you and Twilio can access them.

Learn more here, and check out our guide to securing your Servlet application by validating incoming Twilio requests.


Examine media on incoming WhatsApp messages

examine-media-on-incoming-whatsapp-messages page anchor

Viewing, saving, or manipulating the media files on incoming WhatsApp messages also involves configuring a Webhook URL. The URL points to a server generating TwiML instructions including the media you want to send.

Get incoming message details

get-incoming-message-details page anchor

When Twilio calls your webhook, it sends a number of parameters about the message you just received. Most of these, such as the To phone number, the From phone number, and the Body of the message are available as properties of the request parameter to our action method.

Twilio sends form variables named MediaUrlX, where X is a zero-based index. WhatsApp messages will only contain one media file per incoming message, so you can access the file at MediaUrl0 on the incoming request from Twilio to your webhook URL.

Determine Content-Type of media

determine-content-type-of-media page anchor

Attachments to WhatsApp messages can be of many different file types, including JPG, MP3, and PDF. (See more about the supported file types in the FAQs(link takes you to an external page).) Twilio handles the determination of the file type for you and you can get the standard mime type(link takes you to an external page) from the MediaContentTypeX parameter. If you are expecting photos and images, then you will likely see a lot of attachments with the mime type image/jpeg.

And that's all there is to it; receiving and responding is exactly the same as you would do in any SMS app with our Messaging API. Cool, right?


All the code, in a complete working project, is available on GitHub. To dig deeper, head over to the Messaging API Reference and learn more about the Twilio webhook request and the REST API Media resource. Also, you should be aware of the pricing(link takes you to an external page) for storage of all the media files that you keep on Twilio's servers.

We'd love to hear what you build with this!


Rate this page: