Messages API

The Messages API lets you send messages across multiple channels, WhatsApp, Facebook Messenger, Instagram, and Telegram, directly from your own app or backend.

This is useful for:

• Sending transactional updates (order status, appointment reminders)

• Sending media (images/files) where supported

• Sending WhatsApp templates (for outreach or 24-hour window messages)

• Scheduling messages to be delivered later

VIDEO GUIDE:

Base URL (API Host)

Use this as your API host:

• https://api.dmly.io/rest

All endpoints below are relative to this host.

Authentication

All requests require your API key in the header:

• Header: x-api-key: YOUR_API_KEY

Example:

-H "x-api-key: YOUR_API_KEY"

Core Message Rules (Important)

1) Send to a Contact or a Phone Number (WhatsApp)

For WhatsApp endpoints, you must send to either:

• contact (an existing DMLY contact with an id)
  OR

• recipient (a direct object with phoneNumber)

✅ Allowed:

• contact: { id: "..." }

• recipient: { phoneNumber: "+15551234567" }

❌ Not allowed:

• Sending both contact and recipient in the same request.

2) Workspace is required

Every request includes:

• workspace: { id: "WORKSPACE_ID" }

3) Optional scheduling

To schedule delivery later, include:

• scheduleDateTime: "YYYY-MM-DD HH:mm:ss" (format depends on your implementation, but keep it consistent)

Endpoints Summary

WhatsApp

1. Send WhatsApp Text Message
   POST /v1/messages/whatsapp/sendtext

2. Send WhatsApp Media Message
   POST /v1/messages/whatsapp/sendmedia

3. Send WhatsApp Template Message
   POST /v1/messages/whatsapp/sendtemplate

Facebook Messenger

4. Send Messenger Text Message
   POST /v1/messages/messenger/sendtext

5. Send Messenger Media Message
   POST /v1/messages/messenger/sendmedia

6. Send Messenger Template Message
   POST /v1/messages/messenger/sendtemplate

Instagram

7. Send Instagram Text Message
   POST /v1/messages/instagram/sendtext

8. Send Instagram Template Message
   POST /v1/messages/instagram/sendtemplate

Telegram

9. Send Telegram Template Message
   POST /v1/messages/telegram/sendtemplate

Request Body Schemas (What DMLY expects)

A) TextMessageRequest (general pattern)

Used for Messenger/Instagram text and also as the base idea for WhatsApp text:

{
  "contact": { "id": "CONTACT_ID" },
  "workspace": { "id": "WORKSPACE_ID" },
  "textMessage": "string",
  "scheduleDateTime": "string"
}

B) WhatsAppTextMessageRequest (special rule: contact OR recipient)

{
  "contact": { "id": "CONTACT_ID" },
  "recipient": { "phoneNumber": "+15551234567" },
  "workspace": { "id": "WORKSPACE_ID" },
  "textMessage": "string",
  "scheduleDateTime": "string"
}

You must provide either contact or recipient. Not both.

C) WhatsAppMediaMessageRequest

{
  "contact": { "id": "CONTACT_ID" },
  "recipient": { "phoneNumber": "+15551234567" },
  "workspace": { "id": "WORKSPACE_ID" },
  "mediaUrl": "https://example.com/file.jpg",
  "mimeType": "image/jpeg",
  "scheduleDateTime": "string"
}

D) WhatsAppTemplateMessageRequest

{
  "contact": { "id": "CONTACT_ID" },
  "recipient": { "phoneNumber": "+15551234567" },
  "workspace": { "id": "WORKSPACE_ID" },
  "template": "string"
}

E) TemplateMessageRequest (Messenger/Instagram/Telegram templates)

Templates use an elements or structured payload format depending on the channel.

MessengerTemplateMessageRequest / InstagramTemplateMessageRequest (as shown):

{
  "contact": { "id": "CONTACT_ID" },
  "workspace": { "id": "WORKSPACE_ID" },
  "elements": [
    { "buttons": [], "title": "string" }
  ]
}

TelegramTemplateMessageRequest (as shown):

{
  "contact": { "id": "CONTACT_ID" },
  "workspace": { "id": "WORKSPACE_ID" },
  "buttons": [],
  "textMessage": "string"
}

Practical Examples (cURL)

1) Send a WhatsApp text (to an existing contact)

curl -X POST "https://api.dmly.io/rest/v1/messages/whatsapp/sendtext" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "contact": { "id": "CONTACT_ID" },
    "workspace": { "id": "WORKSPACE_ID" },
    "textMessage": "Hi! This is DMLY. How can I help you today?"
  }'

2) Send a WhatsApp text (to a direct phone number)

curl -X POST "https://api.dmly.io/rest/v1/messages/whatsapp/sendtext" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "recipient": { "phoneNumber": "+15551234567" },
    "workspace": { "id": "WORKSPACE_ID" },
    "textMessage": "Hello! Your appointment is confirmed for tomorrow."
  }'

3) Send a Messenger text

curl -X POST "https://api.dmly.io/rest/v1/messages/messenger/sendtext" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "contact": { "id": "CONTACT_ID" },
    "workspace": { "id": "WORKSPACE_ID" },
    "textMessage": "Thanks for reaching out — how can we assist?"
  }'

4) Schedule a message

Just add scheduleDateTime:

"scheduleDateTime": "2026-02-18 10:30"

Response Format

The Messages API returns a MessageResponse object similar to:

{
  "id": "string",
  "status": "string",
  "error": "string"
}

• status typically indicates success/failure state

• error is usually empty on success, populated when something fails

Best Practices

• Validate inputs before sending (workspace id, contact id, phone number format, etc.)

• Log status + error for debugging delivery issues.

• Prefer contacts where possible (cleaner tracking, better history continuity in Unified Inbox).

• Use templates appropriately, especially for WhatsApp outreach or when outside the allowed messaging window.

• Schedule responsibly (avoid bursts; spread sends to reduce rate-limit risk).

Common Issues & Fixes

• 401/403 Unauthorized

  • Missing/invalid x-api-key

• WhatsApp request rejected

  • You sent both contact and recipient (send only one)

• Message not delivered

  • Channel disconnected, recipient unavailable, or template not approved (WhatsApp)

  • Check connection status in Integrations and re-connect if needed