Sign in Support

API Reference

Messages

Send free-form session messages (text, media, location, Cloud interactive/commerce) and fetch message details.

Session vs template On Cloud API, free-form sends require an open ~24h customer care window. Outside that window use Templates. Full decision table: Session Window vs Templates.
POST /messages messages:send https://staging-mobile.washeej.com/v1/messages

Send a free-form session message (text, media, location, or Cloud interactive/commerce) on Cloud or Device channels.

Parameter Type Required Description
mobile_code string required Country dial code without +.
mobile string required National number digits only.
whatsapp_account_id integer optional Preferred channel ID from GET /devices. Use this in multi-number accounts.
from_number string optional Alternative channel selector — digits only, no + or spaces.
message string optional Text body or media caption. Required unless sending media/interactive/location/product.
image file optional Image upload (multipart).
document file optional Document upload (multipart).
video file optional Video upload (multipart).
audio file optional Audio upload (multipart). On Device channels, pair with ptt=1 for a voice note.
ptt boolean optional Device channels only. true sends audio as a WhatsApp voice note. Prefer OGG/Opus (audio/ogg). webm/opus without ptt is sent as a file.
latitude number optional Location latitude (send with longitude).
longitude number optional Location longitude (send with latitude).
name string optional Optional location title.
address string optional Optional location address line.
cta_url_id integer optional Dashboard CTA URL asset ID (Cloud only).
interactive_list_id integer optional Dashboard interactive list ID (Cloud only).
product json optional Commerce product payload (Cloud).
created_order_data json optional Commerce order payload (Cloud).
cURL 
curl -X POST https://staging-mobile.washeej.com/v1/messages \
  -H "client-id: YOUR_CLIENT_ID" \
  -H "client-secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "mobile_code": "966",
    "mobile": "500000000",
    "whatsapp_account_id": YOUR_ACCOUNT_ID,
    "message": "Hello from Washeej API"
  }'
Response 
{
    "ok": true,
    "data": {
        "conversation_id": 20717,
        "message": {
            "id": 300541,
            "whatsapp_message_id": "wamid.XXX",
            "media_url": null,
            "media_download_path": null
        }
    },
    "meta": {
        "request_id": "uuid"
    }
}
Notes
  • Inside the Cloud 24-hour customer care window you can send free-form messages. Outside that window use templates — see Guides → Session Window.
  • Prefer whatsapp_account_id on multi-number accounts — see Guides → Channel Selection.
  • Device/QR sends go through the device session (GOWA), not Meta Graph. Cloud/Coexistence still use Graph.
  • Session media: multipart file fields (image, document, video, audio). URL fields (image_url, document_url, …) are not supported on POST /v1/messages — see Guides → Session Media.
  • CTA / lists / product require Cloud API — see Guides → Interactive Messages.
  • Returned message.media_url is GET /v1/messages/{id}/media (same client-id / client-secret). It is never a GOWA statics/media path.
  • Cloud numbers may return billing_blocked when Meta payment eligibility fails.
  • Success returns HTTP 201 Created; data.message is the full stored message (id, whatsapp_message_id, media_url, media_download_path, and media_access when the message has media).
  • Optional Idempotency-Key header (1-128 chars): a retry with the same key and the same request returns the first response (header Idempotent-Replayed: true) and sends nothing again; the same key with a different request returns 409 idempotency_conflict, a key still being processed 409 idempotency_in_flight. Keys are kept 24 h per account and credential. Without the header the call behaves as before.

Common errors: billing_blocked, validation_error, capability_error, not_found, invalid_phone

GET /messages/{id} messages:read https://staging-mobile.washeej.com/v1/messages/{id}

Get a single message by Washeej message ID.

Parameter Type Required Description
id path integer required Internal message ID.
cURL 
curl -H "client-id: YOUR_CLIENT_ID" \
     -H "client-secret: YOUR_CLIENT_SECRET" \
     https://staging-mobile.washeej.com/v1/messages/300541
Notes
  • message.media_url is an authenticated Washeej URL. Do not append it to app.washeej.com as a public static file.
GET /messages/{id}/media messages:read https://staging-mobile.washeej.com/v1/messages/{id}/media

Download media for a message you own (Cloud or Device).

Parameter Type Required Description
id path integer required Internal message ID.
cURL 
curl -H "client-id: YOUR_CLIENT_ID" \
     -H "client-secret: YOUR_CLIENT_SECRET" \
     --output note.ogg \
     https://staging-mobile.washeej.com/v1/messages/300541/media
Notes
  • Authenticate with the same client-id and client-secret headers as other v1 GETs.
  • Response is the binary file (Content-Type from the stored MIME). JSON 404 when the message has no media or is not yours.
  • Device inbound files are stored under Washeej after GOWA delivery. Relative GOWA paths such as statics/media/… are not public on app.washeej.com.

Channel targeting

ChannelHow to targetSession rules
Cloud API whatsapp_account_id (preferred) or from_number Free-form inside 24h; templates outside
Device / QR whatsapp_account_id or from_number Routes through GOWA; no Meta template requirement

Details: Channel Selection.

Downloading media

REST and webhook media_url values point to GET /v1/messages/{id}/media. Authenticate with the same client-id / client-secret. Relative GOWA paths such as statics/media/… are not public on app.washeej.com.

Common send patterns

Previous← Conversations NextTemplates →