Send Messages

Overview

The /v1/messages endpoint lets you send messages to any WhatsApp user. Messages can be:

• Text messages — plain text, up to 4,096 characters
• Template messages — pre-approved templates for outbound messaging
• Interactive messages — buttons, lists, and quick replies
• Location messages — share GPS coordinates
• Contact messages — share vCards

Send a Text Message

curl -X POST https://api.startmessaging.com/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "type": "text",
    "text": {
      "body": "Hello! Your order #1234 has been shipped.",
      "preview_url": false
    }
  }'

Response

{
  "success": true,
  "message_id": "msg_abc123def456",
  "status": "accepted",
  "timestamp": "2026-01-15T10:30:00Z"
}

Send a Template Message

Template messages are required for initiating conversations (outside the 24-hour window) or for sending notifications.

curl -X POST https://api.startmessaging.com/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "type": "template",
    "template": {
      "name": "order_confirmation",
      "language": { "code": "pt_BR" },
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "João" },
            { "type": "text", "text": "#ORD-5678" },
            { "type": "text", "text": "R$ 149,90" }
          ]
        }
      ]
    }
  }'

Send an Interactive Message (Buttons)

curl -X POST https://api.startmessaging.com/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "type": "interactive",
    "interactive": {
      "type": "button",
      "body": { "text": "Would you like to track your order?" },
      "action": {
        "buttons": [
          { "type": "reply", "reply": { "id": "track_yes", "title": "Track Order" } },
          { "type": "reply", "reply": { "id": "track_no", "title": "No Thanks" } }
        ]
      }
    }
  }'

Send a Location Message

curl -X POST https://api.startmessaging.com/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "type": "location",
    "location": {
      "latitude": -23.5505,
      "longitude": -46.6333,
      "name": "StartMessaging Office",
      "address": "São Paulo, SP, Brazil"
    }
  }'

Message Status

After sending, messages go through these statuses:

Status	Description
accepted	Message received by StartMessaging
sent	Delivered to WhatsApp servers
delivered	Delivered to the user’s device
read	User opened/read the message
failed	Delivery failed (see error code)

Track delivery via webhooks.

Error Handling

Common errors when sending messages:

Error Code	Description	Solution
INVALID_RECIPIENT	Phone number not on WhatsApp	Verify the number is registered
TEMPLATE_NOT_FOUND	Template doesn’t exist	Check template name and language
OUTSIDE_WINDOW	24h session expired	Use a template message instead
RATE_LIMITED	Too many requests	Implement exponential backoff

FAQ

Can I send messages to any phone number? You can only send messages to numbers that are registered on WhatsApp. For outbound messaging outside the 24-hour window, you must use an approved template message.

What’s the maximum message size? Text messages support up to 4,096 characters. Template messages have variable limits based on the template structure.

How do I know if a message was delivered? Set up webhooks to receive real-time delivery status updates.