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
Use this as your API host:
https://api.dmly.io/api
All endpoints below are relative to this host.
All requests require your API key in the header:
Header: x-api-key: YOUR_API_KEY
Example:
-H "x-api-key: YOUR_API_KEY"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.
Every request includes:
workspace: { id: "WORKSPACE_ID" }
To schedule delivery later, include:
scheduleDateTime: "YYYY-MM-DD HH:mm:ss" (format depends on your implementation, but keep it consistent)
Send WhatsApp Text Message
POST /v1/messages/whatsapp/sendtext
Send WhatsApp Media Message
POST /v1/messages/whatsapp/sendmedia
Send WhatsApp Template Message
POST /v1/messages/whatsapp/sendtemplate
Send Messenger Text Message
POST /v1/messages/messenger/sendtext
Send Messenger Media Message
POST /v1/messages/messenger/sendmedia
Send Messenger Template Message
POST /v1/messages/messenger/sendtemplate
Send Instagram Text Message
POST /v1/messages/instagram/sendtext
Send Instagram Template Message
POST /v1/messages/instagram/sendtemplate
Send Telegram Template Message
POST /v1/messages/telegram/sendtemplate
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"
}{
"contact": { "id": "CONTACT_ID" },
"recipient": { "phoneNumber": "+15551234567" },
"workspace": { "id": "WORKSPACE_ID" },
"textMessage": "string",
"scheduleDateTime": "string"
}You must provide either
contactorrecipient. Not both.
{
"contact": { "id": "CONTACT_ID" },
"recipient": { "phoneNumber": "+15551234567" },
"workspace": { "id": "WORKSPACE_ID" },
"mediaUrl": "https://example.com/file.jpg",
"mimeType": "image/jpeg",
"scheduleDateTime": "string"
}{
"contact": { "id": "CONTACT_ID" },
"recipient": { "phoneNumber": "+15551234567" },
"workspace": { "id": "WORKSPACE_ID" },
"template": "string"
}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"
}curl -X POST "https://api.dmly.io/api/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?"
}'curl -X POST "https://api.dmly.io/api/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."
}'curl -X POST "https://api.dmly.io/api/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?"
}'Just add scheduleDateTime:
"scheduleDateTime": "2026-02-18 10:30"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
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).
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