Send WhatsApp Messages

Send messages to your customers via WhatsApp using the official WhatsApp Business API.

Prerequisites

Before sending WhatsApp messages, you must:

1. Create a WhatsApp Business Account — Register via the dashboard
2. Verify your business — Submit business verification documents
3. Set up a phone number — Register a phone number as your sender
4. Accept opt-in — Recipients must have opted in to receive WhatsApp messages

⚠️ Opt-in Requirement: You must have explicit consent from recipients before sending WhatsApp messages. Sending unsolicited messages violates WhatsApp's policies and may result in account suspension.

Endpoint

POST https://api.galatext.com/api/whatsapp/messages

Headers

Header	Value	Required
Content-Type	application/json	Yes
x-api-key	Your API key	Yes

Request Body

Parameter	Type	Required	Description
phoneNumber	string	Yes	Recipient phone number in E.164 format
type	string	Yes	Message type: text, image, document, video, template
text	object	Conditional	Text message body (required when type is text)
image	object	Conditional	Image media object (required when type is image)
document	object	Conditional	Document media object (required when type is document)
video	object	Conditional	Video media object (required when type is video)
template	object	Conditional	Template message object (required when type is template)
recipientType	string	No	individual (default) or group

Text Messages

Example Request

curl -X POST https://api.galatext.com/api/whatsapp/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "phoneNumber": "+254712345678",
    "type": "text",
    "text": {
      "body": "Hello! Welcome to our WhatsApp service. How can we help you today?"
    }
  }'

{
  "success": true,
  "data": {
    "messageId": "wam_abc123def456",
    "status": "SENT",
    "phoneNumber": "+254712345678",
    "channel": "whatsapp",
    "creditsUsed": 1,
    "creditsRemaining": 499
  }
}

JavaScript (fetch)

const response = await fetch('https://api.galatext.com/api/whatsapp/messages', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.GALATEXT_API_KEY
  },
  body: JSON.stringify({
    phoneNumber: '+254712345678',
    type: 'text',
    text: {
      body: 'Hello! Welcome to our WhatsApp service.'
    }
  })
});

const data = await response.json();

Media Messages

Image

curl -X POST https://api.galatext.com/api/whatsapp/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "phoneNumber": "+254712345678",
    "type": "image",
    "image": {
      "link": "https://your-cdn.com/images/promotion.jpg",
      "caption": "Check out our latest deals!"
    }
  }'

Document

curl -X POST https://api.galatext.com/api/whatsapp/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "phoneNumber": "+254712345678",
    "type": "document",
    "document": {
      "link": "https://your-cdn.com/docs/receipt.pdf",
      "caption": "Your payment receipt",
      "filename": "receipt-june-2025.pdf"
    }
  }'

Video

curl -X POST https://api.galatext.com/api/whatsapp/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "phoneNumber": "+254712345678",
    "type": "video",
    "video": {
      "link": "https://your-cdn.com/videos/tutorial.mp4",
      "caption": "Quick setup tutorial"
    }
  }'

Media Object Fields

Field	Type	Required	Description
link	string	Yes	Public URL of the media file (HTTPS only)
caption	string	No	Media caption (max 1024 characters)
filename	string	No	Filename (document only, max 240 characters)

Supported media formats:

Type	Formats	Max Size
Image	JPEG, PNG, WEBP	5 MB
Document	PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX	100 MB
Video	MP4, 3GPP	16 MB

Template Messages

See the Templates documentation for details on creating and managing WhatsApp message templates.

curl -X POST https://api.galatext.com/api/whatsapp/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "phoneNumber": "+254712345678",
    "type": "template",
    "template": {
      "name": "order_confirmation",
      "language": {
        "code": "en"
      },
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "Alice" },
            { "type": "text", "text": "ORD-12345" },
            { "type": "text", "text": "KES 2,500" }
          ]
        }
      ]
    }
  }'

Opt-In Requirements

WhatsApp requires that recipients have opted in before you send messages. Methods to collect opt-in:

• Checkbox on website — Add a WhatsApp opt-in checkbox to your signup forms
• SMS opt-in — Send a link via SMS for recipients to opt in
• QR code — Display a QR code that triggers opt-in
• Existing relationship — Confirm opt-in via existing communication channels

Your opt-in records may be audited by Meta/WhatsApp at any time.

Response

Success

{
  "success": true,
  "data": {
    "messageId": "wam_abc123def456",
    "status": "SENT",
    "phoneNumber": "+254712345678",
    "channel": "whatsapp",
    "creditsUsed": 1,
    "creditsRemaining": 499
  }
}

Error

{
  "success": false,
  "error": {
    "code": "WHATSAPP_OPT_IN_REQUIRED",
    "message": "Recipient has not opted in to receive WhatsApp messages from this business.",
    "statusCode": 403
  }
}

Error Codes

Status	Error Code	Description
400	BAD_REQUEST	Malformed request body
401	UNAUTHORIZED	Missing or invalid API key
403	WHATSAPP_OPT_IN_REQUIRED	Recipient has not opted in
403	WHATSAPP_NUMBER_NOT_REGISTERED	Sender number not registered
422	INVALID_MEDIA_URL	Media URL is invalid or inaccessible
429	RATE_LIMIT_EXCEEDED	Too many requests

Best Practices

• Always obtain opt-in before sending messages
• Use templates for business-initiated conversations
• Respond quickly to customer messages (24-hour window)
• Monitor opt-out and respect recipients' preferences
• Keep media small — Optimize images and videos for WhatsApp