Sending messages via API

Send WhatsApp messages programmatically from your application, CRM, or automation tools.

Endpoint

POST https://app.aisoule.com/api/messages/send

Authentication

Include your API key in the header:

X-API-Key: your_api_key_here

Sending a text message

curl -X POST https://app.aisoule.com/api/messages/send \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "type": "text",
    "text": "Hello! Your order has been shipped."
  }'

Note: Text messages only work within the 24-hour window.

Sending a template message

curl -X POST https://app.aisoule.com/api/messages/send \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "type": "template",
    "template": {
      "name": "order_confirmation",
      "language": "en",
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "John" },
            { "type": "text", "text": "ORD-789" }
          ]
        }
      ]
    }
  }'

Sending media

curl -X POST https://app.aisoule.com/api/messages/send \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "type": "image",
    "image": {
      "url": "https://example.com/product.jpg",
      "caption": "Check out our new product!"
    }
  }'

Supported media types: image, video, document, audio

Sending interactive messages

Buttons

{
  "to": "+919876543210",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "body": { "text": "How can we help?" },
    "action": {
      "buttons": [
        { "type": "reply", "reply": { "id": "sales", "title": "Sales" } },
        { "type": "reply", "reply": { "id": "support", "title": "Support" } }
      ]
    }
  }
}

Response format

Success:

{
  "data": {
    "message_id": "wamid.HBgLOTE5ODc2NTQzMjEw...",
    "status": "sent"
  }
}

Error:

{
  "message": "Outside 24-hour window. Use a template message.",
  "status": "error"
}

Specifying WhatsApp account

If you have multiple accounts, specify which one to send from:

{
  "to": "+919876543210",
  "type": "text",
  "text": "Hello!",
  "whatsapp_account": "account_id_here"
}

If not specified, the default outgoing account is used.

Rate limits

• 100 messages per minute via API
• 10 messages per second burst
• Meta's messaging limits still apply (unique contacts per day)

Error codes

Tips

1. Use templates for first contact — Text messages fail outside the window
2. Handle errors gracefully — Implement retry logic for 429 and 500 errors
3. Validate phone numbers — Include country code, digits only
4. Log message IDs — Useful for tracking delivery via webhooks
5. Test in sandbox — Use a test number before production