Sending Messages

All message types use a single endpoint. The type field determines the payload shape.

Endpoint: POST /v1/phones/{phoneId}/messages

Common Fields

Field Type Required Description
type string Yes Message type (see sections below)
to string Yes Recipient phone number with country code (e.g. "5491155551234")

Response

All message types return the same response:

{
  "data": {
    "messageId": "550e8400-e29b-41d4-a716-446655440000",
    "wamid": "wamid.HBgLNTQ5MTE1NTU..."
  }
}

Text Message

{
  "type": "text",
  "to": "5491155551234",
  "text": "Hello, how can I help you?",
  "previewUrl": false
}
Field Type Required Description
text string Yes Message body
previewUrl boolean No Enable URL preview (default: false)

Media Messages (Image, Video, Audio, Document, Sticker)

Send media by URL or by pre-uploaded media ID.

With a media URL:

{
  "type": "image",
  "to": "5491155551234",
  "mediaUrl": "https://example.com/photo.jpg",
  "caption": "Check out this photo!"
}

With a pre-uploaded media ID:

{
  "type": "document",
  "to": "5491155551234",
  "mediaId": "1234567890",
  "caption": "Monthly report",
  "filename": "report-march-2026.pdf"
}
Field Type Required Description
type string Yes "image", "video", "audio", "document", or "sticker"
mediaId string No* WhatsApp media ID (from upload endpoint)
mediaUrl string No* Public URL to the media file
caption string No Caption text (image, video, document only)
filename string No Filename (document only)

*Either mediaId or mediaUrl must be provided, but not both.

Uploading Media

POST /v1/phones/{phoneId}/media with Content-Type: multipart/form-data and a file field.

Returns { "data": { "id": "1234567890" } }

Template Message

{
  "type": "template",
  "to": "5491155551234",
  "templateName": "order_confirmation",
  "languageCode": "en_US",
  "parameters": {
    "header": [
      { "type": "text", "text": "Order #1234" }
    ],
    "body": [
      { "type": "text", "text": "John" },
      { "type": "text", "text": "$99.00" }
    ],
    "buttons": [
      {
        "type": "button",
        "subType": "url",
        "index": 0,
        "parameters": [
          { "type": "text", "text": "order-1234" }
        ]
      }
    ]
  }
}
Field Type Required Description
templateName string Yes Template name as registered in Meta
languageCode string Yes Language code (e.g. "en_US", "es_AR")
parameters object No Header, body, and button parameters

Interactive Button Message

{
  "type": "interactive",
  "to": "5491155551234",
  "interactiveType": "button",
  "body": "How would you like to proceed?",
  "header": { "type": "text", "text": "Choose an option" },
  "footer": "Reply within 24 hours",
  "buttons": [
    { "id": "btn_buy", "title": "Buy Now" },
    { "id": "btn_info", "title": "More Info" },
    { "id": "btn_cancel", "title": "Cancel" }
  ]
}
Field Type Required Description
interactiveType string Yes Must be "button"
body string Yes Message body text
header object No { type: "text", text: string }
footer string No Footer text
buttons array Yes 1-3 buttons: { id: string, title: string } (title max 20 chars)

Interactive List Message

{
  "type": "interactive",
  "to": "5491155551234",
  "interactiveType": "list",
  "body": "Browse our catalog:",
  "buttonText": "View Products",
  "sections": [
    {
      "title": "Electronics",
      "rows": [
        { "id": "phone_1", "title": "Smartphone X", "description": "Latest model" },
        { "id": "laptop_1", "title": "Laptop Pro", "description": "16-inch display" }
      ]
    }
  ]
}
Field Type Required Description
interactiveType string Yes Must be "list"
body string Yes Message body text
buttonText string Yes Text on the list button (max 20 chars)
sections array Yes At least 1 section with title and rows

CTA URL Message

{
  "type": "cta_url",
  "to": "5491155551234",
  "bodyText": "Visit our store for exclusive deals",
  "buttonText": "Open Store",
  "url": "https://store.example.com",
  "headerText": "Special Offer",
  "footerText": "Offer expires soon"
}

Flow Message

Before sending a Flow, create and publish it through the Flows guide.

{
  "type": "flow",
  "to": "5491155551234",
  "bodyText": "Complete your registration",
  "flowToken": "token_abc123",
  "flowId": "1234567890",
  "flowCta": "Start Registration",
  "flowAction": "navigate",
  "screen": "WELCOME_SCREEN",
  "data": { "userId": "usr_123" }
}

Mark Message as Read

POST /v1/phones/{phoneId}/messages/{messageId}/read

messageId is the WhatsApp message ID (wamid).

{ "showTypingIndicator": false }