API reference

Send a message

POST /v1/developer/messages - send text, media, or voice via a connected device.

Outbound messages are sent through a connected WhatsApp number - a linked device or a Meta number, using the same routes. Every request needs a deviceUid (from GET /v1/developer/devices) and a recipient phone number in E.164-ish format (matching ^\+?[0-9]{7,15}$).

Send text

POST https://api.msgera.io/v1/developer/messages/send
X-API-Key: <MSGERA_KEY>
Content-Type: application/json

Request body

Field	Type	Description
`deviceUid`required	`string`	UID of the WhatsApp device sending the message.
`to`required	`string`	Recipient phone number, matching ^\+?[0-9]{7,15}$.
`text`	`string`	Message body (min 1 character). Supports spintax. Required unless templateId is set.
`templateId`	`string`	Approved template to send instead of text (Meta numbers). See the next section.
`variables`	`string[]`	Values for the template placeholders {{1}}, {{2}}, … in order.
`clientMessageId`	`string`	Your own idempotency key - duplicate values are deduped.

curl -X POST https://api.msgera.io/v1/developer/messages/send \
  -H "X-API-Key: $MSGERA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceUid": "dev_4f8c2a1e",
    "to": "+15551234567",
    "text": "Hello from Msgera"
  }'

Send an approved template

Meta numbers can only send free-form text, media and voice to contacts who wrote to the number in the last 24 hours. For anyone else, send an approved template on the same route by adding templateId (list them with GET /v1/developer/templates?deviceUid=). The recipient needs recorded WhatsApp opt-in.

curl -X POST https://api.msgera.io/v1/developer/messages/send \
  -H "X-API-Key: $MSGERA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceUid": "wa_dev_Q2xvdWROdW1iZXI",
    "to": "+15551234567",
    "templateId": "8b7d1c2e-3f4a-4b5c-9d6e-7f8a9b0c1d2e",
    "variables": ["Maria", "#1042"]
  }'

TEMPLATE_REQUIRED

Sending text to a contact whose 24-hour window is closed returns 422 TEMPLATE_REQUIRED. Retry the same request with a templateId. Linked devices don't use templates: templateId there returns 422 CAPABILITY_UNAVAILABLE.

Send media

Upload an image, video, or document first with POST /v1/developer/media/upload, then reference its mediaId:

POST https://api.msgera.io/v1/developer/messages/send-media
X-API-Key: <MSGERA_KEY>
Content-Type: application/json

Field	Type	Description
`deviceUid`required	`string`	UID of the WhatsApp device.
`to`required	`string`	Recipient phone number.
`mediaId`required	`string`	Id returned by /v1/developer/media/upload.
`caption`	`string`	Optional caption shown below the media.
`clientMessageId`	`string`	Your own idempotency key - duplicate values are deduped.

Send voice

Same flow as media, but the upload should be an audio file. The recipient sees it as a voice note in WhatsApp.

POST https://api.msgera.io/v1/developer/messages/send-voice
X-API-Key: <MSGERA_KEY>
Content-Type: application/json

Field	Type	Description
`deviceUid`required	`string`	UID of the WhatsApp device.
`to`required	`string`	Recipient phone number.
`mediaId`required	`string`	Id of the uploaded audio asset.
`clientMessageId`	`string`	Your own idempotency key.

Check WhatsApp availability

Before broadcasting, you can verify whether a list of numbers is on WhatsApp. The check runs on a connected linked device on your account. When none is available the response has verified: false and every number is reported as existing.

POST https://api.msgera.io/v1/developer/messages/check-whatsapp
X-API-Key: <MSGERA_KEY>
Content-Type: application/json

Field	Type	Description
`deviceUid`required	`string`	UID of the WhatsApp device.
`numbers`required	`string[]`	1-50 phone numbers to check.

Sending limits on linked devices

Identical wording can reach at most 8 different numbers per device in 24 hours - beyond that sends fail with 422 DUPLICATE_BROADCAST. Vary the text with spintax or use a campaign. Sends to numbers that never messaged the device are capped per day; extra messages stay PENDING and go out after the next UTC midnight. See Account Safety.

Idempotency for media & voice

Pass a stable clientMessageId to safely retry on network errors. Msgera deduplicates by this value per device.

Want delivery confirmations pushed to you? Subscribe your webhook to message.status to receive SENT, DELIVERED, READ and FAILED updates - see Webhook events. Replies arrive as message.inbound events.