Messaging Overview

Core Endpoint

The main Cloud API messaging endpoint is:

POST https://graph.facebook.com/<GRAPH_VERSION>/<PHONE_NUMBER_ID>/messages

Use this endpoint for text messages, template messages, media messages, and interactive messages.

Text Messages

Text messages are the default type for free-form conversation replies.

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "12015550123",
  "type": "text",
  "text": {
    "preview_url": false,
    "body": "Hello, world"
  }
}

Response:

{
  "messaging_product": "whatsapp",
  "contacts": [
    { "input": "12015550123", "wa_id": "12015550123" }
  ],
  "messages": [
    { "id": "wamid.HBgLMTIwMTU1NTAxMjMVAgARGBI..." }
  ]
}

Text Formatting

Text messages support basic formatting:

• Bold: *text*
• Italic: _text_
• Strikethrough: ~text~
• Monospace: triple backticks

Message body maximum length: 4096 characters.

URL Preview Behavior

URL previews are controlled using text.preview_url:

• false (default) — no URL preview
• true — preview can be generated for eligible links

The preview is generated for the first URL in the text. The URL must start with http:// or https://. Links to media files usually do not render rich previews.

Delivery Status Lifecycle

Common outbound status progression:

1. sent — message accepted by Meta
2. delivered — message delivered to recipient device
3. read — read receipt confirmed (if applicable)

These statuses arrive asynchronously through webhook callbacks to your endpoint.

Mark Message as Read

{
  "messaging_product": "whatsapp",
  "status": "read",
  "message_id": "wamid.HBgLMTIwMTU1NTAxMjMVAgARGBI..."
}

Typing Indicator

Show a typing indicator while preparing a response:

{
  "messaging_product": "whatsapp",
  "status": "read",
  "message_id": "wamid.HBgLMTIwMTU1NTAxMjMVAgARGBI...",
  "typing_indicator": {
    "type": "text"
  }
}

• Requires a valid incoming message_id from the user.
• Only works on the most recent incoming user message.
• Indicator auto-dismisses after ~25 seconds if no follow-up message is sent.
• If preconditions are not met, the request may be ignored without an explicit API error.

Bulk Messaging

For bulk operations, use approved templates and strict opt-in hygiene. Large-volume sends should include rate control, retries, quality monitoring, and suppression for opt-outs and non-responsive users.

Common Messaging Errors

For a full error reference, see Meta API Error Reference. Dualhook does not proxy message content — message events route via Webhook Override directly from Meta to your endpoint.