Complete guide to sending all types of WhatsApp messages through Evolution API Lite

Sending Messages

Evolution API Lite provides comprehensive support for sending all types of WhatsApp messages. This guide covers every message type with detailed examples and payload structures.

info All message endpoints require authentication via API key and a valid instance name. Make sure your instance is connected before sending messages.

Common Parameters

All message types share these common parameters:

number (required): The recipient's phone number in international format (e.g., "5511999999999")
delay (optional): Delay in milliseconds before sending the message
quoted (optional): Reference to a message being replied to
mentioned (optional): Array of phone numbers to mention in the message
linkPreview (optional): Enable/disable link preview for text messages

Text Messages

Send simple text messages with optional formatting and mentions.

Endpoint

POST /message/{instanceName}/sendText

Request Body

{
  "number": "5511999999999",
  "text": "Hello! This is a test message."
}

{
  "number": "5511999999999@g.us",
  "text": "Hello @5511888888888! How are you?",
  "mentioned": ["5511888888888"]
}

{
  "number": "5511999999999",
  "text": "This is a reply to your message",
  "quoted": {
    "key": {
      "id": "message_id_here",
      "remoteJid": "5511999999999@s.whatsapp.net",
      "fromMe": false
    },
    "message": {}
  }
}

cURL Example

curl -X POST "https://your-api-url/message/your-instance/sendText" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "number": "5511999999999",
    "text": "Hello from Evolution API!"
  }'

Media Messages

Send images, videos, audio files, and documents with optional captions.

Endpoint

POST /message/{instanceName}/sendMedia

Supported Media Types

image: JPEG, PNG, WebP images
video: MP4, AVI, MOV videos
audio: MP3, WAV, OGG audio files
document: PDF, DOC, TXT and other document formats

Request Body

{
  "number": "5511999999999",
  "mediatype": "image",
  "media": "https://example.com/image.jpg",
  "caption": "Check out this amazing photo!"
}

{
  "number": "5511999999999",
  "mediatype": "document",
  "media": "data:application/pdf;base64,JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwo+PgplbmRvYmoK...",
  "fileName": "important-document.pdf",
  "caption": "Please review this document"
}

{
  "number": "5511999999999",
  "mediatype": "video",
  "media": "https://example.com/video.mp4",
  "caption": "Watch this video!"
}

Media Sources

You can provide media in three ways:

URL: Direct link to the media file
Base64: Encoded media data with proper data URI format
File Upload: Use multipart/form-data with a file field

cURL Example with File Upload

curl -X POST "https://your-api-url/message/your-instance/sendMedia" \
  -H "apikey: your-api-key" \
  -F "number=5511999999999" \
  -F "mediatype=image" \
  -F "caption=Uploaded image" \
  -F "file=@/path/to/image.jpg"

Audio Messages

Send WhatsApp voice messages with special audio formatting.

Endpoint

POST /message/{instanceName}/sendWhatsAppAudio

Request Body

{
  "number": "5511999999999",
  "audio": "https://example.com/audio.mp3"
}

warn Audio messages are automatically converted to WhatsApp's voice message format. Use regular media messages for music or other audio files.

cURL Example

curl -X POST "https://your-api-url/message/your-instance/sendWhatsAppAudio" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "number": "5511999999999",
    "audio": "https://example.com/voice-message.mp3"
  }'

Button Messages

Send interactive messages with clickable buttons.

Endpoint

POST /message/{instanceName}/sendButtons

Button Types

reply: Simple reply button
url: Opens a URL
call: Initiates a phone call
copy: Copies text to clipboard
pix: PIX payment button (Brazil)

Request Body

{
  "number": "5511999999999",
  "title": "Choose an Option",
  "description": "Please select one of the options below:",
  "footer": "Evolution API",
  "buttons": [
    { "type": "reply", "displayText": "Option 1", "id": "option_1" },
    { "type": "reply", "displayText": "Option 2", "id": "option_2" }
  ]
}

{
  "number": "5511999999999",
  "title": "Contact Us",
  "description": "Get in touch with our team",
  "buttons": [
    {
      "type": "url",
      "displayText": "Visit Website",
      "url": "https://example.com"
    },
    {
      "type": "call",
      "displayText": "Call Support",
      "phoneNumber": "5511888888888"
    },
    {
      "type": "copy",
      "displayText": "Copy Email",
      "copyCode": "support@example.com"
    }
  ]
}

cURL Example

curl -X POST "https://your-api-url/message/your-instance/sendButtons" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "number": "5511999999999",
    "title": "Quick Actions",
    "buttons": [
      {
        "type": "reply",
        "displayText": "Yes",
        "id": "yes"
      },
      {
        "type": "reply",
        "displayText": "No",
        "id": "no"
      }
    ]
  }'

List Messages

Send interactive lists with multiple sections and options.

Endpoint

POST /message/{instanceName}/sendList

Request Body

{
  "number": "5511999999999",
  "title": "Product Catalog",
  "description": "Browse our available products",
  "footerText": "Select an item to learn more",
  "buttonText": "View Products",
  "sections": [
    {
      "title": "Electronics",
      "rows": [
        {
          "title": "Smartphone",
          "description": "Latest model with advanced features",
          "rowId": "phone_001"
        },
        {
          "title": "Laptop",
          "description": "High-performance laptop for work",
          "rowId": "laptop_001"
        }
      ]
    },
    {
      "title": "Accessories",
      "rows": [
        {
          "title": "Wireless Headphones",
          "description": "Premium sound quality",
          "rowId": "headphones_001"
        }
      ]
    }
  ]
}

cURL Example

curl -X POST "https://your-api-url/message/your-instance/sendList" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "number": "5511999999999",
    "title": "Menu Options",
    "buttonText": "Select Option",
    "sections": [
      {
        "title": "Main Menu",
        "rows": [
          {
            "title": "Order Food",
            "description": "Browse our menu",
            "rowId": "order"
          }
        ]
      }
    ]
  }'

Poll Messages

Create interactive polls with multiple choice options.

Endpoint

POST /message/{instanceName}/sendPoll

Request Body

{
  "number": "5511999999999@g.us",
  "name": "What's your favorite programming language?",
  "selectableCount": 1,
  "values": ["JavaScript", "Python", "TypeScript", "Java", "Go"]
}

Parameters

name: The poll question
selectableCount: Number of options users can select (1-10)
values: Array of poll options (2-10 items)

cURL Example

curl -X POST "https://your-api-url/message/your-instance/sendPoll" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "number": "5511999999999@g.us",
    "name": "Best time for the meeting?",
    "selectableCount": 1,
    "values": ["Morning", "Afternoon", "Evening"]
  }'

Sticker Messages

Send animated or static stickers.

Endpoint

POST /message/{instanceName}/sendSticker

Request Body

{
  "number": "5511999999999",
  "sticker": "https://example.com/sticker.webp"
}

info Stickers should be in WebP format for best compatibility. The API will attempt to convert other formats automatically.

cURL Example

curl -X POST "https://your-api-url/message/your-instance/sendSticker" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "number": "5511999999999",
    "sticker": "data:image/webp;base64,UklGRiQAAABXRUJQVlA4IBgAAAAwAQCdASoBAAEAAwA0JaQAA3AA/vuUAAA="
  }'

Location Messages

Share location coordinates with optional name and address.

Endpoint

POST /message/{instanceName}/sendLocation

Request Body

{
  "number": "5511999999999",
  "latitude": -23.5505,
  "longitude": -46.6333,
  "name": "São Paulo Cathedral",
  "address": "Praça da Sé, São Paulo, SP, Brazil"
}

cURL Example

curl -X POST "https://your-api-url/message/your-instance/sendLocation" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "number": "5511999999999",
    "latitude": -23.5505,
    "longitude": -46.6333,
    "name": "Meeting Point"
  }'

Contact Messages

Share contact information with vCard format.

Endpoint

POST /message/{instanceName}/sendContact

Request Body

{
  "number": "5511999999999",
  "contact": [
    {
      "fullName": "John Doe",
      "wuid": "5511888888888",
      "phoneNumber": "+55 11 88888-8888",
      "organization": "Example Company",
      "email": "john@example.com",
      "url": "https://johndoe.com"
    }
  ]
}

Multiple Contacts

{
  "number": "5511999999999",
  "contact": [
    {
      "fullName": "John Doe",
      "wuid": "5511888888888",
      "phoneNumber": "+55 11 88888-8888"
    },
    {
      "fullName": "Jane Smith",
      "wuid": "5511777777777",
      "phoneNumber": "+55 11 77777-7777"
    }
  ]
}

cURL Example

curl -X POST "https://your-api-url/message/your-instance/sendContact" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "number": "5511999999999",
    "contact": [
      {
        "fullName": "Support Team",
        "wuid": "5511888888888",
        "phoneNumber": "+55 11 88888-8888"
      }
    ]
  }'

Reaction Messages

Add emoji reactions to existing messages.

Endpoint

POST /message/{instanceName}/sendReaction

Request Body

{
  "key": {
    "id": "message_id_here",
    "remoteJid": "5511999999999@s.whatsapp.net",
    "fromMe": false
  },
  "reaction": "👍"
}

Removing Reactions

To remove a reaction, send an empty string:

{
  "key": {
    "id": "message_id_here",
    "remoteJid": "5511999999999@s.whatsapp.net",
    "fromMe": false
  },
  "reaction": ""
}

cURL Example

curl -X POST "https://your-api-url/message/your-instance/sendReaction" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "key": {
      "id": "message_id_here",
      "remoteJid": "5511999999999@s.whatsapp.net",
      "fromMe": false
    },
    "reaction": "❤️"
  }'

Template Messages

Send WhatsApp Business template messages (requires approved templates).

Endpoint

POST /message/{instanceName}/sendTemplate

Request Body

{
  "number": "5511999999999",
  "name": "hello_world",
  "language": "en_US",
  "components": [
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "John"
        }
      ]
    }
  ]
}

warn Template messages require WhatsApp Business API approval and pre-approved message templates. This feature is typically used with Meta's Cloud API integration.

Status Messages

Send messages to WhatsApp Status (Stories).

Endpoint

POST /message/{instanceName}/sendStatus

Request Body

{
  "type": "text",
  "content": "Hello from Evolution API!",
  "backgroundColor": "#FF5733",
  "font": 1
}

{
  "type": "image",
  "content": "https://example.com/status-image.jpg",
  "caption": "Check this out!"
}

{
  "type": "text",
  "content": "Private status message",
  "statusJidList": ["5511999999999", "5511888888888"]
}

Status Types

text: Text-only status with background color
image: Image status with optional caption
video: Video status with optional caption
audio: Audio status

Error Handling

All message endpoints return standardized error responses:

{
  "error": true,
  "message": "Error description",
  "details": {
    "code": "VALIDATION_ERROR",
    "field": "number"
  }
}

Common Errors

Invalid number format: Phone number must be in international format
Instance not connected: The WhatsApp instance is not connected
Media validation failed: Invalid media URL or base64 format
Rate limit exceeded: Too many messages sent in a short period

Best Practices

Validate Phone Numbers

Always use international format without '+' symbol (e.g., "5511999999999")

Handle Media Properly

For documents, always include fileName. For base64 media, ensure proper data URI format.

Implement Error Handling

Always check response status and handle errors appropriately in your application.

Respect Rate Limits

Implement delays between messages to avoid being blocked by WhatsApp.

Use Webhooks

Configure webhooks to receive message status updates and delivery confirmations.

Next Steps

Learn about Group Management for group-specific messaging
Set up Webhooks to receive message status updates
Explore the API documentation on Postman: https://www.postman.com/agenciadgcode/evolution-api/overview

Sending Messages

On this page