Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.msgflash.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Endpoint

POST /api/v1/messages/send
Authentication: x-api-key: <api_key> The message is accepted as queued, then sent asynchronously.
From the MsgFlash dashboard, media can be prepared through a temporary upload before final sending. See Temporary media uploads.

​
Parameters

​
Body

FieldTypeRequiredDescription
instanceIdUUIDyesSource WhatsApp instance
tostringyesE.164 number
typeenumyes if no templateIdDirect message type
templateIdUUIDyes if no typeMsgFlash template to use
textstringdepends on typeDirect message body
mediaUrlstringdepends on typePublic media URL
latitudenumberif type=locationLatitude
longitudenumberif type=locationLongitude
locationNamestringnoLocation name
locationAddressstringnoLocation address
contactIdUUIDnoShared contact or template context
variablesobjectnoValues injected into custom.*
This route has no path or query parameters.

​
Mode 1 — Direct message

​
Texte

curl -X POST https://srv.msgflash.com/api/v1/messages/send \
  -H "x-api-key: msgf_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "YOUR_INSTANCE_ID",
    "to": "+33612345678",
    "type": "text",
    "text": "Hello, your order is ready."
  }'

​
Media, location, and contact

{
  "instanceId": "YOUR_INSTANCE_ID",
  "to": "+33612345678",
  "type": "image",
  "mediaUrl": "https://cdn.example.com/banner.jpg",
  "text": "Nouvelle collection"
}

​
Mode 2 — Send via template

You can send a message by providing templateId instead of type. 
curl -X POST https://srv.msgflash.com/api/v1/messages/send \
  -H "x-api-key: msgf_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "YOUR_INSTANCE_ID",
    "to": "+33612345678",
    "contactId": "CONTACT_UUID",
    "templateId": "TEMPLATE_UUID",
    "variables": {
      "app": "MsgFlash",
      "coupon": "PROMO10"
    }
  }'
The backend:
  • loads the template
  • resolves contact.*, user.*, instance.*
  • injects your custom values into custom.*
  • stores the final rendered text in Message.body
Template example: 
Hello {{contact.firstName}}, bienvenue sur {{custom.app}} depuis {{instance.name}}.
Supported variables:
  • contact.*
  • user.*
  • instance.*
  • custom.*
For contact.* variables, provide contactId if you want enriched contact context.

​
Success response

{
  "data": {
    "id": "msg_uuid",
    "instanceId": "inst_uuid",
    "contactId": "cnt_uuid",
    "campaignId": null,
    "type": "text",
    "to": "+33612345678",
    "body": "Hello Awa, bienvenue sur MsgFlash depuis Boutique Porto-Novo.",
    "mediaUrl": null,
    "status": "queued",
    "providerMessageId": null,
    "createdAt": "2026-04-01T10:00:00.000Z",
    "updatedAt": "2026-04-01T10:00:00.000Z"
  }
}

​
Common errors

CodeHTTPWhen
VALIDATION_ERROR400Invalid body
TEMPLATE_INVALID400Invalid placeholder or template
TEMPLATE_VARIABLES_MISSING400Variables template missing
TEMPLATE_CONTEXT_UNAVAILABLE400Invalid contactId or instanceId context
NOT_FOUND404Instance, contact, or template not found
SUBSCRIPTION_INACTIVE403Subscription not usable
MONTHLY_OUTBOUND_QUOTA_EXCEEDED429Monthly quota exhausted

​
Possible statuses

queued → sent → delivered → read
                   └──────→ failed
StatusDescription
queuedMessage accepted and queued
sentSent to WhatsApp
deliveredDelivered to the device
readRead by recipient
failedSend failed

​
Track status

  1. GET /api/v1/messages/{id}
  2. Webhooks message.sent, message.delivered, message.read, message.failed
See Webhooks.