Send Simple Message

Send a simple text message to a specific phone number via WhatsApp.

📌

Important | 24-Hour Customer (Service Window)
Simple text messages are subject to Meta's customer service window policy. You can only send free-form text messages within 24 hours of the customer's last message to your business. This window starts or refreshes whenever the customer messages or calls you. After this 24-hour window expires, the message will not be delivered. Use approved template messages for communication beyond the 24-hour window.

Contact Behavior

If contact exists by phone number → Message sent to existing contact

If contact doesn't exist AND contact object provided → New contact created with provided data, then message sent

If contact doesn't exist AND no contact object → New contact created with phone number as name, then message sent

Contact Creation Requirements

If contact object is provided, the specified data will be used

If no contact object is provided, a basic contact will be created automatically using the phone number as the firstname

firstname defaults to phone number if not provided in contact data

lastname defaults to empty string if not provided

Contact will be created as type "lead" with WhatsApp Auto Lead settings applied

If WhatsApp Auto Lead is enabled, default status, source, and assignee will be applied automatically

Request

Authorization

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Path Params

Header Params

Body Params application/jsonRequired

Example

{
  "phone_number": "+201XXXXXXXXX",
  "message_body": "Hello! This is a sample message to demonstrate the API.",
  "contact": {
    "firstname": "Mahmoud",
    "lastname": "Elsayed",
    "email": "mahmoud@example.com",
    "country": "Egypt",
    "groups": "VIP Customers,Newsletter Subscribers"
  }
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200Success

application/json

Body

Example

{
  "status": "success",
  "message": "Message sent successfully",
  "data": {
    "message_id": "wamid.HBgMOTE5ODEwNjAwMDAwFQIAERgSNUU1RjE4MUM0QjY5MjFFNzYzAA==",
    "contact_id": 15,
    "phone": "+201XXXXXXXXX",
    "message": "Hello! This is a sample message to demonstrate the API.",
    "status": "sent",
    "sent_at": "2024-02-08 14:30:25",
    "chat_id": 8,
    "contact_created": true
  }
}

🟠400Bad Request

🟠401Unauthenticated

🟠403Conversation Limit Reached

🟠422Validation Errors

🔴500Whatsapp Api Error (Meta)