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

Rich Messaging Features in the Twilio API for WhatsApp


When you build with the WhatsApp Business API with Twilio, you get access to several WhatsApp-specific features to dress up your messages and make it easier for your end users to reach you.

These features include:

  • Formatting message text
  • Including location information
  • Displaying previews of web links
  • QR Codes and Short Links
  • Deep Links

Formatting in WhatsApp Messages

formatting-in-whatsapp-messages page anchor

WhatsApp allows text, emojis, and some formatting in messages. To format all or part of a message, use these formatting symbols:

FormattingSymbolExample
BoldAsterisk (**)Your total is $10.50.
ItalicUnderscore (_)Welcome to WhatsApp!
Strike-throughTilde (~)This is better best!
Code / Pre-formattedThree backticks (```)print 'Hello World';

Send a formatted WhatsApp message

send-a-formatted-whatsapp-message page anchor

Use symbols to format your WhatsApp messaage

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_15
// Download the helper library from https://www.twilio.com/docs/node/install
_15
// Find your Account SID and Auth Token at twilio.com/console
_15
// and set the environment variables. See http://twil.io/secure
_15
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_15
const authToken = process.env.TWILIO_AUTH_TOKEN;
_15
const client = require('twilio')(accountSid, authToken);
_15
_15
client.messages
_15
.create({
_15
from: 'whatsapp:+15005550006',
_15
messagingServiceSid: 'MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
_15
body: '🎶I am _not_ ~pushing~ throwing away my *shot*!',
_15
to: '+15558675310'
_15
})
_15
.then(message => console.log(message.sid));

Output

_24
{
_24
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"api_version": "2010-04-01",
_24
"body": "🎶I am _not_ ~pushing~ throwing away my *shot*!",
_24
"date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"direction": "outbound-api",
_24
"error_code": null,
_24
"error_message": null,
_24
"from": "whatsapp:+15005550006",
_24
"num_media": "0",
_24
"num_segments": "1",
_24
"price": null,
_24
"price_unit": null,
_24
"messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"status": "queued",
_24
"subresource_uris": {
_24
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json"
_24
},
_24
"to": "+14155552345",
_24
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_24
}

WhatsApp message displaying italics, strike-through, and bolding.

Location Messages with WhatsApp

location-messages-with-whatsapp page anchor

The Twilio API for WhatsApp supports sending and receiving GPS location data in messages to and from WhatsApp users.

(warning)

Warning

Facebook does not support location messaging in WhatsApp Message Templates at this time. Twilio Conversations also does not support location messaging functionality at this time. To send and receive location messages with WhatsApp, you'll need to use session messages leveraging the API or Twilio's helper libraries.

Send outbound location messages

send-outbound-location-messages page anchor

Sending outbound location messages over WhatsApp is similar to sending a text-based message, with the addition of the PersistentAction parameter in your Twilio API requests. Outbound location messages must include the following information:

  • Body={name}
  • PersistentAction=geo:{latitude},{longitude} OR
  • PersistentAction=geo:{latitude},{longitude}|{label}
NameTypeRequiredDescription
nameStringYes (for outbound messages)The name of the location being sent.(Location must exist in Google maps for the hyperlink to work on Mac/Windows WhatsApp client)
latitudeNumberYesLatitude of the location being sent
longitudeNumberYesLongitude of the location being sent
labelStringNoOptional free-form text to display under the location name

Send a WhatsApp message with location information

send-a-whatsapp-message-with-location-information page anchor

Use the persistent_action parameter

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_15
// Download the helper library from https://www.twilio.com/docs/node/install
_15
// Find your Account SID and Auth Token at twilio.com/console
_15
// and set the environment variables. See http://twil.io/secure
_15
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_15
const authToken = process.env.TWILIO_AUTH_TOKEN;
_15
const client = require('twilio')(accountSid, authToken);
_15
_15
client.messages
_15
.create({
_15
messagingServiceSid: 'MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
_15
body: 'This is one of the Twilio office locations',
_15
persistentAction: ['geo:37.787890,-122.391664|375 Beale St'],
_15
to: 'whatsapp:+15005550006'
_15
})
_15
.then(message => console.log(message.sid));

Output

_24
{
_24
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"api_version": "2010-04-01",
_24
"body": "This is one of the Twilio office locations",
_24
"date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"direction": "outbound-api",
_24
"error_code": null,
_24
"error_message": null,
_24
"from": "+14155552345",
_24
"num_media": "0",
_24
"num_segments": "1",
_24
"price": null,
_24
"price_unit": null,
_24
"messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"status": "queued",
_24
"subresource_uris": {
_24
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json"
_24
},
_24
"to": "whatsapp:+15005550006",
_24
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_24
}

Your user should receive a message that looks like this:

WhatsApp message containing location information, it shows a map for 375 Beale St in San Francisco.

Receive inbound location messages

receive-inbound-location-messages page anchor

You can also receive inbound location messages with the Twilio API for WhatsApp.

Locations do not appear in the Twilio Console(link takes you to an external page) at this time. However, your web application will receive the location data in the POST request that Twilio sends. This data will be included in the HTTP POST request for the incoming message that we send to your webhook.

You will be able to access the following parameters in the POST request values Twilio sends to your application when you receive a WhatsApp location message:

  • Latitude
  • Longitude
  • Address
  • Label

There are two types of location that users can send with WhatsApp: Current Location and Live Location. Live Location is not currently supported by the WhatsApp Business API.

Current Location is a static type of content, similar to a timestamp. This means the location information you receive from a user indicates where the user was in that particular moment in time when they triggered the "send location" action.

Below is a sample payload containing location information. Please note that the Body={name} parameter is not required for inbound messages.


_10
Latitude=37.7879277&Longitude=-122.3937508&Address=375+Beale+St%2C+San+Francisco%2C+CA+94105&SmsMessageSid=SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&NumMedia=0&SmsSid=SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&Label=Twilio+Inc&Body=&To=whatsapp%3A%2B14155238886&NumSegments=1&MessageSid=SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&AccountSid=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&From=whatsapp%3A%2B12345678900&ApiVersion=2010-04-01

A QR ("Quick Response") code is a type of barcode that you can use to open up a new WhatsApp conversation. Your end uses can scan your business' QR code(link takes you to an external page), and the WhatsApp business profile will automatically load, with a pre-filled message that your business can define.

Here's an example of a QR Code:

sample_whatsapp_qr_code.

Quick Replies and Call to Action buttons

quick-replies-and-call-to-action-buttons page anchor

WhatsApp lets you add different types of buttons to message templates: "Quick Replies" and "Call to Action" buttons. For more information on buttons check out the guide on Using Buttons In WhatsApp.


Twilio Messaging Content API

twilio-messaging-content-api page anchor

Twilio's Content API offers rich features on OTT channels including quick replies, lists, cards, media and more.


Ready to send feature-rich messages to your end users over WhatsApp? Check out some of these resources to get started (or keep) building:


Rate this page: