Send a WhatsApp message (inbound) via the Kanal API

Endpoint

POST https://api.getkanal.com/api/v1/messages/send

Authentication

Every request must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Your API key is tied to a WhatsApp Business number. All messages are sent from this number.

Prerequisites

The contact must have sent a message within the last 24 hours (WhatsApp conversation window). Without an active conversation, use the /v1/templates endpoint to send an approved template.

Supported message types

Text

{
  "to": "33612345678",
  "type": "text",
  "text": {
    "body": "Hello, here is your projection!"
  }
}

Image

{
  "to": "33612345678",
  "type": "image",
  "image": {
    "link": "https://example.com/photo.jpg",
    "caption": "Find this product here 👉 https://example.com/product"
  }
}

Video

{
  "to": "33612345678",
  "type": "video",
  "video": {
    "link": "https://example.com/video.mp4",
    "caption": "Discover our product on video"
  }
}

Audio

{
  "to": "33612345678",
  "type": "audio",
  "audio": {
    "link": "https://example.com/audio.mp3"
  }
}

Document

{
  "to": "33612345678",
  "type": "document",
  "document": {
    "link": "https://example.com/invoice.pdf"
  }
}

Idempotency

To avoid duplicate sends, add an idempotency-key header with a unique identifier:

idempotency-key: my-unique-id-123

If a message has already been sent with this key, the API returns a 201 without sending the message again.

Response

Success (200):

{
  "success": true,
  "message": "Message sent successfully",
  "message_id": 12345,
  "contact_id": 678,
  "phone_number": "33612345678"
}

Common errors:

Code

Reason

cURL examples

Text

curl -X POST https://api.getkanal.com/api/v1/messages/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "33612345678",
    "type": "text",
    "text": {
      "body": "Hello, here is your projection!"
    }
  }'

Image

curl -X POST https://api.getkanal.com/api/v1/messages/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "33612345678",
    "type": "image",
    "image": {
      "link": "https://example.com/projection.jpg",
      "caption": "Find this product here 👉 https://example.com/product"
    }
  }'

Video

curl -X POST https://api.getkanal.com/api/v1/messages/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "33612345678",
    "type": "video",
    "video": {
      "link": "https://example.com/video.mp4",
      "caption": "Discover our product on video"
    }
  }'

Audio

curl -X POST https://api.getkanal.com/api/v1/messages/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "33612345678",
    "type": "audio",
    "audio": {
      "link": "https://example.com/audio.mp3"
    }
  }'

Document

curl -X POST https://api.getkanal.com/api/v1/messages/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "33612345678",
    "type": "document",
    "document": {
      "link": "https://example.com/invoice.pdf"
    }
  }'