Send message
https://whatsapp.paaltech.org/api/v1/businesses/{external_id}/messages
Token ability:
messages.send
ยท Authentication
Queues a text, template or media (image, video, audio, document) message - on WhatsApp, or
with channel sms or email (text; set up with Set up SMS or email).
SMS and email are always business-initiated, so suppression, consent and quiet hours apply. 202 = a new
message, queued; 200 = this reference was already submitted and the original message
is returned (nothing is sent again). Progress arrives as message.status callbacks.
Free-form text and media need an open 24-hour customer service window; otherwise send an
APPROVED template. For media, upload the file first and pass its
media.id (businesses with media enabled).
Path parameters
external_id
string
required
Your own ID for the business (Multi-SKUUL - the tenant ID).
Max 191 characters. Pattern ^[A-Za-z0-9._:-]+$.
Body parameters
channel
string
SMS and email send type text (email also needs subject); the business must have the channel set up.
One of: whatsapp, sms, email. Default "whatsapp".
to
string
required
International digits, optional leading + (an email address for email).
subject
string | null
Email only.
Max 200 characters.
type
string
required
One of: text, template, image, video, audio, document.
text
object
Required when type is text; not allowed otherwise.
body
string
required
text.body
Max 4096 characters.
preview_url
boolean
text.preview_url
Default false.
template
object
Required when type is template; not allowed otherwise.
name
string
required
template.name
Max 512 characters.
language
string
required
template.language
Max 20 characters.
components
array of objects
template.components
Meta's send-time components (header/body/button parameters).
Max 20 items.
media
object
Required when type is image, video, audio or document; not allowed otherwise. The file must suit the type.
id
integer
required
media.id
PaalChat's media ID, from Upload media (or an incoming message's media_id).
caption
string | null
media.caption
Images, videos and documents.
Max 1024 characters.
filename
string | null
media.filename
Documents; defaults to the uploaded name.
Max 240 characters.
category
string | null
Templates only - the consent category checked. Defaults from the template (MARKETING -> marketing, AUTHENTICATION -> transactional, else notifications).
One of: marketing, notifications, transactional, ``.
topic
string | null
Templates only - refused if the contact turned this topic off.
One of: fees, results, attendance, pta, marketing, system, ``.
send_at
string | null
Templates only - send at this time (up to 90 days ahead); held until then and cancellable with Cancel scheduled message. Quiet hours still apply at that time.
Format date-time.
urgent
boolean
Templates only - skip the business's quiet hours. Needs the messages.urgent ability.
Default false.
reference
string | null
Your ID for the message - the idempotency key. Strongly recommended.
Max 191 characters. Pattern ^[\x21-\x7E]+$.
phone_number_id
string | null
Required only when the business has several connected numbers.
Responses
Duplicate reference - the original message, with its current status.
Queued.
unauthenticated - missing, invalid, revoked or expired token
missing_ability, product_suspended or product_token_required
not_found (business), unknown_phone_number or unknown_media.
not_connected, connection_paused, business_suspended or media_not_ready.
validation_failed, outside_service_window, unknown_template, template_not_approved, phone_number_required, media_type_mismatch, recipient_suppressed, recipient_opted_out , recipient_preference_off or invalid_template_parameters.
rate_limited - over 300 requests/minute for this product
Errors always look like {"error": {"code", "message"}} - see Errors and status codes.