Messages

Send to a phone number, an email address or an existing contact. The contact and conversation are found or created for you.

Send a message

Queues the message and returns it with status PENDING. to is { "type": "WHATSAPP", "phone": "+62…" }, { "type": "EMAIL", "address": "…" }, { "type": "TELEGRAM", "userId": "…" } or { "contactId": "…" }.

Scopemessage:send

channelIdstringrequired

The channel that sends the message. Copy it from the channel page (Channel ID), or list them with GET /api/v1/channel. Signed in, pick a channel at the top of the docs to fill it into the examples.

toobjectrequired

The recipient: { "type": "WHATSAPP", "phone" }, { "type": "EMAIL", "address" }, { "type": "TELEGRAM", "userId" } or { "contactId" }.

contentobjectrequired

The message: TEXT, IMAGE, DOCUMENT, LOCATION and more. See the content types below.

replyToMessageIdstring

Quote an earlier message of the same conversation.

POSThttps://www.beamvia.com/api/v1/message

curl -X POST "https://www.beamvia.com/api/v1/message" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "CHANNEL_ID",
    "to": {
      "type": "WHATSAPP",
      "phone": "+6281234567890"
    },
    "content": {
      "type": "TEXT",
      "text": "Hello from Beamvia!"
    }
  }'

{
  "status": true,
  "message": "Message queued",
  "data": {
    "message": {
      "id": "6650f0c2a1b2c3d4e5f60718",
      "conversationId": "6650f0c2a1b2c3d4e5f60700",
      "direction": "OUTBOUND",
      "author": {
        "type": "API",
        "apiKeyId": "6650f0c2a1b2c3d4e5f60001"
      },
      "content": {
        "type": "TEXT",
        "text": "Hello from Beamvia!"
      },
      "status": "PENDING",
      "isPrivate": false,
      "replyTo": null,
      "external": {
        "id": null
      },
      "sentAt": "2026-10-20T08:00:00.000Z"
    }
  }
}

Content types

The same content shape is used for every channel. Unsupported types for a channel or plan are rejected.

type	Fields
TEXT	text
IMAGE · VIDEO · DOCUMENT	file { url, mimetype, filename?, driveId? }, caption?
AUDIO	file, isVoice?
STICKER	file
LOCATION	latitude, longitude, name?, address?
CONTACT	name, phone?, email?
REACTION	messageId (external id), emoji

Media must be a publicly reachable URL (private and local addresses and redirects are refused, up to 100 MB). The file is downloaded and sent by the channel.

Or set driveId to send a file already in your workspace's drive (uploaded from the dashboard). Files of other workspaces are refused with "File not found". File URLs you receive (API, webhooks, plugins) are stable links: they keep working until the file is deleted.

Delivery status

Messages are queued and move through these statuses. Subscribe to MESSAGE_UPDATED to follow them.

status	Meaning
PENDING	Queued, not yet handed to the channel
SENT	Accepted by the channel
DELIVERED	Delivered to the recipient's device
READ	Read by the recipient
FAILED	Sending failed after retries; see error