Skip to content
NexisChat Docs

Sending Messages

Sending Messages

Section titled “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.

Common Parameters

Section titled “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

Section titled “Text Messages”

Send simple text messages with optional formatting and mentions.

Endpoint

Section titled “Endpoint”
POST /message/{instanceName}/sendText

Request Body

Section titled “Request Body”
{
  "number": "5511999999999",
  "text": "Hello! This is a test message."
}

cURL Example

Section titled “cURL Example”
Terminal window
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

Section titled “Media Messages”

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

Endpoint

Section titled “Endpoint”
POST /message/{instanceName}/sendMedia

Supported Media Types

Section titled “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

Section titled “Request Body”
{
  "number": "5511999999999",
  "mediatype": "image",
  "media": "https://example.com/image.jpg",
  "caption": "Check out this amazing photo!"
}

Media Sources

Section titled “Media Sources”

You can provide media in three ways:

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

cURL Example with File Upload

Section titled “cURL Example with File Upload”
Terminal window
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

Section titled “Audio Messages”

Send WhatsApp voice messages with special audio formatting.

Endpoint

Section titled “Endpoint”
POST /message/{instanceName}/sendWhatsAppAudio

Request Body

Section titled “Request Body”
{
  "number": "5511999999999",
  "audio": "https://example.com/audio.mp3"
}

cURL Example

Section titled “cURL Example”
Terminal window
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

Section titled “Button Messages”

Send interactive messages with clickable buttons.

Endpoint

Section titled “Endpoint”
POST /message/{instanceName}/sendButtons

Button Types

Section titled “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

Section titled “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" }
  ]
}

cURL Example

Section titled “cURL Example”
Terminal window
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

Section titled “List Messages”

Send interactive lists with multiple sections and options.

Endpoint

Section titled “Endpoint”
POST /message/{instanceName}/sendList

Request Body

Section titled “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

Section titled “cURL Example”
Terminal window
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

Section titled “Poll Messages”

Create interactive polls with multiple choice options.

Endpoint

Section titled “Endpoint”
POST /message/{instanceName}/sendPoll

Request Body

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

Parameters

Section titled “Parameters”
  • name: The poll question
  • selectableCount: Number of options users can select (1-10)
  • values: Array of poll options (2-10 items)

cURL Example

Section titled “cURL Example”
Terminal window
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

Section titled “Sticker Messages”

Send animated or static stickers.

Endpoint

Section titled “Endpoint”
POST /message/{instanceName}/sendSticker

Request Body

Section titled “Request Body”
{
  "number": "5511999999999",
  "sticker": "https://example.com/sticker.webp"
}

cURL Example

Section titled “cURL Example”
Terminal window
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

Section titled “Location Messages”

Share location coordinates with optional name and address.

Endpoint

Section titled “Endpoint”
POST /message/{instanceName}/sendLocation

Request Body

Section titled “Request Body”
{
  "number": "5511999999999",
  "latitude": -23.5505,
  "longitude": -46.6333,
  "name": "Sao Paulo Cathedral",
  "address": "Praca da Se, Sao Paulo, SP, Brazil"
}

cURL Example

Section titled “cURL Example”
Terminal window
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

Section titled “Contact Messages”

Share contact information with vCard format.

Endpoint

Section titled “Endpoint”
POST /message/{instanceName}/sendContact

Request Body

Section titled “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

Section titled “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

Section titled “cURL Example”
Terminal window
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

Section titled “Reaction Messages”

Add emoji reactions to existing messages.

Endpoint

Section titled “Endpoint”
POST /message/{instanceName}/sendReaction

Request Body

Section titled “Request Body”
{
  "key": {
    "id": "message_id_here",
    "remoteJid": "5511999999999@s.whatsapp.net",
    "fromMe": false
  },
  "reaction": "👍"
}

Removing Reactions

Section titled “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

Section titled “cURL Example”
Terminal window
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

Section titled “Template Messages”

Send WhatsApp Business template messages (requires approved templates).

Endpoint

Section titled “Endpoint”
POST /message/{instanceName}/sendTemplate

Request Body

Section titled “Request Body”
{
  "number": "5511999999999",
  "name": "hello_world",
  "language": "en_US",
  "components": [
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "John"
        }
      ]
    }
  ]
}

Status Messages

Section titled “Status Messages”

Send messages to WhatsApp Status (Stories).

Endpoint

Section titled “Endpoint”
POST /message/{instanceName}/sendStatus

Request Body

Section titled “Request Body”
{
  "type": "text",
  "content": "Hello from Evolution API!",
  "backgroundColor": "#FF5733",
  "font": 1
}

Status Types

Section titled “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

Section titled “Error Handling”

All message endpoints return standardized error responses:

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

Common Errors

Section titled “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

Section titled “Best Practices”
  1. Validate Phone Numbers

Always use international format without ’+’ symbol (e.g., “5511999999999”)

  1. Handle Media Properly

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

  1. Implement Error Handling

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

  1. Respect Rate Limits

Implement delays between messages to avoid being blocked by WhatsApp.

  1. Use Webhooks

Configure webhooks to receive message status updates and delivery confirmations.

Next Steps

Section titled “Next Steps”