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

​
Important — how to get instanceId

instanceId is required to send a message. Do not use these instead:
  • name
  • waNumber
To get the correct instanceId:
  1. call GET /api/v1/instances
  2. select the target instance
  3. copy data[n].id
  4. send this value in the instanceId field
Example:
  • id = technical identifier required by the API
  • name = human-readable label
  • waNumber = connected number shown to the user

​
Body

FieldTypeRequiredDescription
instanceIdUUIDyesTechnical identifier of the MsgFlash instance, obtained via GET /api/v1/instances
tostringyesE.164 number
typeenumyes if no templateIdtext, image, video, audio, document, voice_note, location, contact, buttons
templateIdUUIDyes if no typeTemplate to render
textstringdepends on typeBody du message
mediaUrlstringdepends on typePublic media URL
latitudenumberif locationLatitude
longitudenumberif locationLongitude
locationNamestringnoLocation name
locationAddressstringnoAddress
contactIdUUIDnoShared contact or template context
variablesobjectnocustom.* values
titlestringif buttonsButton message title
descriptionstringif buttonsButton message description
footerstringnoButton message footer
buttonsarrayif buttonsList of buttons (max 2)

​
Buttons

Each button must follow this structure: 
{
  "title": "reply", // reply | url | call | copy | pix
  "displayText": "Button text",
  "id": "button_id",
  "url": "https://example.com", // for type url
  "phoneNumber": "+5511999999999", // for type call
  "copyCode": "dGV4dA==", // for type copy
  "currency": "BRL", // for type pix
  "name": "John Doe", // for type pix
  "keyType": "random", // for type pix
  "key": "0ea59ac5-f001-4f0e-9785-c7..." // for type pix
}

​
Request example

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": "INSTANCE_UUID",
    "to": "+33612345678",
    "type": "text",
    "text": "Hello"
  }'

​
Messages with buttons

Messages with buttons require a WhatsApp Business account. They let you add up to 2 interactive buttons.

​
Supported button types

TypeDescriptionRequired fields
replyQuick reply buttondisplayText, id
copyButton to copy textdisplayText, copyCode
urlButton that opens a URLdisplayText, url
callButton to calldisplayText, phoneNumber
pixPix payment button (Brazil)displayText, currency, name, keyType, key

​
Button message example

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": "INSTANCE_UUID",
    "to": "+33612345678",
    "type": "buttons",
    "title": "Choose an option",
    "description": "What would you like to do?",
    "footer": "Reply quickly",
    "buttons": [
      {
        "title": "reply",
        "displayText": "View menu",
        "id": "menu_option"
      },
      {
        "title": "url",
        "displayText": "Visit website",
        "url": "https://example.com"
      }
    ]
  }'

​
Success response 201

{
  "data": {
    "id": "msg_uuid",
    "instanceId": "inst_uuid",
    "contactId": null,
    "campaignId": null,
    "type": "text",
    "to": "+33612345678",
    "body": "Hello",
    "mediaUrl": null,
    "status": "queued",
    "warnings": [
      "This instance is still in the warmup phase."
    ],
    "safety": {
      "decision": "warn",
      "riskLevel": "medium",
      "state": "warming",
      "score": 56,
      "reasons": [
        "This instance is still in the warmup phase."
      ],
      "recommendations": [
        "Start with previously engaged contacts before scaling volume."
      ]
    },
    "error": null,
    "providerMessageId": null,
    "createdAt": "2026-04-01T10:00:00.000Z",
    "updatedAt": "2026-04-01T10:00:00.000Z"
  }
}
In V1, safety warnings do not block sending. They are informational only.

​
Common errors

HTTPCodeWhen
400VALIDATION_ERRORInvalid body
400TEMPLATE_INVALIDTemplate invalid
400TEMPLATE_VARIABLES_MISSINGRequired variables missing
400TEMPLATE_CONTEXT_UNAVAILABLEInvalid contact or instance context
403SUBSCRIPTION_INACTIVESubscription not usable
403UNSUPPORTED_FEATUREUnsupported feature (buttons without WhatsApp Business)
404NOT_FOUNDInstance, contact, or template not found
429MONTHLY_OUTBOUND_QUOTA_EXCEEDEDSending quota exhausted