Skip to content
man glossary/text-message

glossary define text-message

Name

Text Message

The simplest WhatsApp message: a plain text body of up to 4,096 characters, with an optional preview for the first link it contains.

Synopsis

WhatsApp text message, Plain-text message, Text message type

Section

Messages & interactivity

Level

foundation

▍

Reviewed

Will this reply fit in one text message?

1,051 / 4,096 characters

Fits, with 3,045 characters to spare.

One text message carries up to 4,096 characters, counting spaces, emoji, line breaks and formatting markers.

1,051 / 1,024 characters

Over by 27. Text past 1,024 characters is rejected or cut off.

Won’t fit: m and 9 pm, all seven days.

Add reply buttons and the same answer becomes an interactive message, whose body allows only 1,024 characters.

19 / 20 characters

Close to the limit: only 1 left. Keep headroom if part of this text is filled in at send time.

Each reply button's title is limited to 20 characters.

Counted in Unicode code points, so an emoji, ₹ or an accented letter counts as one character.

Edit each field to see how close a reply is to its limit. The same answer that fits easily in a 4,096-character text body is over the 1,024 characters allowed once you add reply buttons.

Description

What is a WhatsApp text message?

A text message is the simplest message type on the WhatsApp Business Platform: a single block of text with no media, buttons or template. Through the Cloud API you send it with a POST to the messages endpoint, setting type to text and putting the content in text.body, which holds up to 4,096 characters, including emoji, line breaks and WhatsApp's formatting markup.

The optional preview_url flag asks the recipient's WhatsApp client to try to render a link preview for the first URL in the body. The URL must start with http:// or https://, and any later URLs appear as ordinary clickable links. Without the flag, or when no preview can be fetched, links are still tappable. Inbound text works the same way in reverse: a messages webhook whose message has type: text and a text.body.

Because it is free-form, a text message is a session message. It can only be sent while the 24-hour customer service window is open, and since 1 October 2026 a reply inside that window in India is billed per delivered message at the service rate, ₹0.145. To start a conversation, or to write after the window has closed, send an approved message template instead. This page is about the message type itself: the markup inside the body is covered under WhatsApp text formatting, the preview card under link preview, and every field cap under message character limits.

Key takeaways

  • A text message is the Cloud API's type: text message: one text.body string of up to 4,096 characters sent to one recipient.
  • Set preview_url: true to let WhatsApp render a preview of the first http(s) link in the body; later links stay plain.
  • Free-form text can only be sent inside an open 24-hour customer service window; outside it, send an approved template.
  • A successful send returns a wamid; delivered, read and failed statuses arrive later by webhook.
  • Add context.message_id to quote the customer's message and answer it as a contextual reply.

Usage

A WhatsApp text message in code

curl -X POST "https://graph.facebook.com/v26.0/{PHONE_NUMBER_ID}/messages" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "919812345678",
    "type": "text",
    "text": {
      "preview_url": true,
      "body": "Yes, 3 in stock at Edappally. Reserve here: https://example.com/r/55tv"
    }
  }'

Properties

A WhatsApp text message: key facts and limits

Message type
type: text, content in text.body
Body limit
4,096 characters
Link preview
First http(s) URL only, with preview_url: true
When allowed
Inside an open 24-hour customer service window
India price
₹0.145 per delivered reply since 1 October 2026
Success response
messages[0].id, the wamid
Endpoint
POST /{PHONE_NUMBER_ID}/messages

Mechanics

How does a WhatsApp text message work?

  1. step 1 — Check the window is open

    A free-form text needs a customer message in the last 24 hours. Look up the conversation's last inbound timestamp; if the window has closed, send a template instead.

  2. step 2 — Build the body

    Set messaging_product: whatsapp, recipient_type: individual, to (country code and number, digits only), type: text and text.body. Add preview_url: true if the first link should show a preview.

  3. step 3 — POST to the messages endpoint

    Send it to https://graph.facebook.com/v26.0/{PHONE_NUMBER_ID}/messages with a bearer access token. A 200 response means the platform accepted the message, not that it was delivered.

  4. step 4 — Store the wamid

    The response's messages[0].id is the message's wamid and contacts[0].wa_id the recipient's WhatsApp ID. Save both with your own message record.

  5. step 5 — Follow the status webhooks

    sent, delivered and read statuses arrive on the messages webhook, keyed by the wamid. A failed status carries an error code, such as 131047 when the window had closed.

Caveats

Common mistakes with a WhatsApp text message

  • Sending free-form text outside the window

    If the customer's last message is more than 24 hours old, the text fails with error 131047. Check the window before sending and fall back to an approved utility or marketing template.

  • Running past 4,096 characters

    Long bot or LLM answers can exceed the limit and are rejected. Cap generated replies, split at paragraph breaks, or send long material as a document.

  • Expecting a preview for every link

    Only the first URL is previewed, and only if the page can be fetched and has preview metadata. Put the link that matters first and keep the others for later messages.

  • Formatting the recipient wrongly

    to takes the country code and number as digits. A leading 0 or a missing 91 sends to the wrong number or fails. Normalise numbers to E.164 when you collect them.

  • Treating 200 as delivered

    A 200 with a wamid means the platform accepted the message. Delivery can still fail later, so drive your UI from the status webhooks, not the send response.

Example

Example: A stock check at a Kochi electronics store

At 7:10 pm a customer asks a Kochi electronics store's WhatsApp number whether a 55-inch TV is in stock at its Edappally branch. The store's bot checks inventory and sends a text message with preview_url set to true: "Yes, 3 in stock at Edappally. Reserve here: https://example.com/r/55tv". The product page's preview appears under the text. The bot stores the returned wamid, and the delivered and read statuses arrive within seconds. When the customer then asks about returns, the bot's long policy answer runs to just over 1,000 characters — fine as text, but too long for an interactive message with buttons, so it sends the policy as text and the "Reserve" button separately.

Why it matters

Why does a WhatsApp text message matter?

Most of what a support team or a bot sends is plain text, so getting the text message right — the recipient format, a sensible length, previews only where they help — is the base of every integration. It is also the quickest end-to-end test of a new setup: if a text to your own phone arrives and its delivered status comes back, the access token, the phone number ID and the webhook loop all work.

Notes

Best practices for a WhatsApp text message

  • Test a new number and token by texting your own phone first.
  • Put the link you want previewed first in the body.
  • Keep bot replies to a few short paragraphs; nobody reads a 4,000-character message on a phone.
  • Use context.message_id when answering one of several questions so the customer sees which one you mean.
  • Store the wamid next to your own message ID so status webhooks can be matched later.

Questions

Text Message FAQs

What is the character limit for a WhatsApp text message?
4,096 characters in text.body. That count includes spaces, emoji, line breaks and formatting markers. Longer content must be split into several messages or sent as a document.
How do I show a link preview in a WhatsApp API message?
Set preview_url to true in the text object. The recipient's app then tries to render a preview for the first http:// or https:// URL in the body; later URLs stay plain links, and if no preview can be fetched the link is still clickable.
Can I send a text message to a customer who has not messaged me?
Not as free-form text. A text message is a session message and needs an open 24-hour customer service window. Start the conversation with an approved template; once the customer replies, you can switch to text messages.
Is a WhatsApp API text message charged?
Yes, in India since 1 October 2026. A text reply inside the service window is billed per delivered message at the service rate, ₹0.145; until 30 September 2026 such replies were free. Undelivered messages are not billed.
How is a text message different from a template message?
A text message is free-form and only allowed inside the window; a template is pre-approved and can be sent at any time. Text needs no review and can say anything relevant to the conversation, while a template's wording is fixed at approval, with variables for the parts that change.

See InfiQ pricing

* Per-message rates for India, ex-GST: marketing, utility and authentication effective 1 July 2026; service messages ₹0.145 since 1 October 2026 (they were ₹0 until 30 September 2026). Volume commitments earn discounts — final rate is confirmed on your account; applicable GST extra. Rates for other countries differ (see the international rate table on /pricing).

Put Text Message to work

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms