WhatsApp is how most clinics actually talk to their patients: appointment reminders, confirmations, x-ray photos, and the replies to all of it. You can read conversations, messages and media with whatsapp:read, send with whatsapp:write, and manage conversation tags with whatsapp_tags:write.
Message bodies are patient conversations
A message body carries whatever a patient chose to tell the clinic, and the media may be a clinical photo. Both are covered by the single whatsapp:read scope - only grant it to integrations that genuinely need to read what patients said.
#Three things to know first
A clinic may run more than one number. Each conversation and message carries the clinic's side as clinic_phone, Numbers lists what the clinic runs, and a send names the line with from. A clinic on a single number can ignore all of this: omitting from sends from the default number.
Message ids are prefixed. Inbound and outbound messages are stored separately, so ids look like in_5312 and out_8842. Treat the whole string as the id - a bare number is not a valid id and will 404.
The 24-hour window governs what you can send. WhatsApp forbids free-form text outside a 24-hour window that reopens each time a patient messages the clinic. Send free text outside it and it goes out wrapped in a marketing template, which is billed differently. The API does not hide this: free_text_window_expires_at on a conversation tells you the window state before you send, and meta.delivery_mode on the response tells you which product was actually used.
#The conversation object
One per patient phone number and clinic number: a patient who has written to two of the clinic's lines has two conversations, each with its own clinic_phone and its own 24-hour window.
| Field | Type | Description |
|---|---|---|
id | string | Unique conversation id. |
display_name | string | null | The patient's WhatsApp profile name. |
patient_phone | string | null | The patient's number, in local 0… form. |
clinic_phone | string | null | The clinic's number this thread runs on - a phone from Numbers. A patient who wrote to two of the clinic's numbers has two conversations. |
last_message_preview | string | null | Text of the most recent message. |
last_activity_at | string | null | ISO 8601 timestamp of the last message either way. |
last_inbound_at | string | null | ISO 8601 timestamp of the last message from the patient. |
last_outbound_at | string | null | ISO 8601 timestamp of the last message to the patient. |
is_handled | boolean | Whether staff marked the thread as dealt with. |
free_text_window_expires_at | string | null | When the 24-hour free-text window closes. null means it is already closed. |
patients | object[] | Patient summaries linked to the thread. |
tags | object[] | The tags staff or an integration put on the thread - { "id", "name", "color" }. |
created_at | string | null | ISO 8601 timestamp. |
updated_at | string | null | ISO 8601 timestamp. |
#The message object
| Field | Type | Description |
|---|---|---|
id | string | Prefixed id - in_… for inbound, out_… for outbound. |
conversation_id | string | null | The thread this belongs to. |
direction | string | inbound or outbound. |
type | string | text, image, document, audio, video, sticker, contacts. |
status | string | received for inbound. For outbound: queued, sent, delivered, read or failed. |
from_phone | string | null | Sender, as stored (outbound uses the international 972… form). |
to_phone | string | null | Recipient, as stored. |
patient_phone | string | null | The patient side, whichever direction the message ran, in local 0… form. |
clinic_phone | string | null | The clinic side, whichever direction - the number this message ran on, as Numbers lists it. |
text | string | null | Message body, or the caption for a media message. |
media | object | { "available": boolean, "type": string | null } - fetch the link separately. |
transcript | object | null | Inbound voice notes only - see below. null for every other message. |
patients | object[] | Patient summaries matched on patient_phone. |
template | string | null | Outbound only: the approved template this went out as, if any. |
components | object[] | null | Outbound only: what the patient was shown - header, body, footer and buttons. See Components. null for inbound. |
replied_to_id | string | null | Inbound only: the outbound message this replies to. |
reactions | object | { "patient": string | null, "clinic": string | null } - each side's current emoji reaction. WhatsApp keeps one per side and replaces it, so this is the current state, not a history. |
failure_reason | string | null | Outbound only: why Meta rejected it. |
timestamps | object | null | Outbound only - see below. null for inbound. |
created_at | string | null | ISO 8601 timestamp. |
updated_at | string | null | ISO 8601 timestamp. Bumps on each delivery receipt, and when a voice note's transcript lands. |
#The transcript object (inbound voice notes)
On clinics with AI features enabled, a voice note a patient sends (an inbound message of type audio) is transcribed automatically, usually within seconds of arriving.
| Field | Type | Description |
|---|---|---|
status | string | null | processing, done, failed, or null when transcription was never attempted (AI features off, or the note arrived before they were turned on). |
text | string | null | What was said, in the language it was spoken - not translated or summarized. Set only when status is done. |
Subscribe to whatsapp.message.transcript.completed to hear when the text lands instead of re-reading the message. A transcript is what the patient said out loud, under the same whatsapp:read scope as the rest of the message.
#The timestamps object (outbound only)
| Field | Type | Description |
|---|---|---|
sent_at | string | null | Accepted by WhatsApp. |
delivered_at | string | null | Reached the patient's handset. |
read_at | string | null | Opened by the patient. Never set if they disabled read receipts. |
failed_at | string | null | Delivery failed; see failure_reason. |
status is derived from these, and terminal beats progress: a message that failed after WhatsApp accepted it reports failed, not sent.
#Components
A sent message and a template describe their parts the same way, following WhatsApp's own model, so whatever draws one can draw the other. Each component has a type; draw the ones you know and skip the rest - new types (a carousel, an offer) are added as new values, never as changes to these.
type | Fields |
|---|---|
header | format: text with text, or image / video / document with media_id - fetch it with Get a message's media (null on a template). |
body | text. On a sent message, the words as delivered; on a template, with its {{n}} placeholders. |
footer | text. |
buttons | buttons: an array of { "type", "text", "url", "phone_number" }. type is url, quick_reply or phone_number. On a sent message text is the label the patient saw and url is the complete link. |
"components": [
{ "type": "body", "text": "Hi Dana, thanks for your interest!" },
{ "type": "buttons", "buttons": [
{ "type": "url", "text": "Book a demo", "url": "https://example.com/schedule", "phone_number": null }
] }
]
When a sent message has no header or footer
Inside the 24-hour window, a MARKETING template can go out as an interactive message, which has a fixed footer of its own and no text header. Which form a message took is not recorded, so for those messages components reports the body, any media header, and the buttons - never a guessed header or footer.
Messages carry no patient foreign key. The link is a phone-number match made when you read, so patients may contain more than one person (a shared household number) or none at all.
#List conversations
curl "https://api.smile-app.co.il/v1/whatsapp/conversations?limit=20" \
-H "Authorization: Bearer sk_live_..."
| Parameter | Description |
|---|---|
phone | Only the thread for this number. Separators are ignored. |
clinic_phone | Only threads on this clinic number. Separators are ignored. |
is_handled | true or false. |
updated_since | ISO 8601. Switches to ascending mutation order for incremental sync. |
limit, cursor | See Pagination. |
Threads come back most-recent-activity first, unless updated_since is set.
#Get a conversation
curl https://api.smile-app.co.il/v1/whatsapp/conversations/318 \
-H "Authorization: Bearer sk_live_..."
#List messages in a conversation
curl "https://api.smile-app.co.il/v1/whatsapp/conversations/318/messages" \
-H "Authorization: Bearer sk_live_..."
Inbound and outbound are merged into one stream, newest first. Accepts the same filters as the cross-conversation listing below.
#List messages
Across every conversation.
curl "https://api.smile-app.co.il/v1/whatsapp/messages?direction=inbound&from=2026-08-01" \
-H "Authorization: Bearer sk_live_..."
| Parameter | Description |
|---|---|
direction | inbound or outbound. |
type | text, image, document, audio, video, sticker, contacts. |
phone | Messages to or from this number. Separators are ignored. |
clinic_phone | Messages that ran on this clinic number, either direction. Separators are ignored. |
from, to | ISO 8601 bounds on the message timestamp. |
updated_since | ISO 8601. Use this to catch delivery receipts on older messages. |
limit, cursor | See Pagination. |
Prefer webhooks, and poll on updated_since
Don't poll for inbound replies - subscribe to whatsapp.message.received instead and you'll hear about a patient's message as it lands, which matters if anything you build answers them.
If you do poll: a delivered or read receipt can land hours after a message was sent, and it bumps updated_at without changing created_at. Poll on updated_since, not from, or you will miss status changes on messages you have already seen.
#Get a message
curl https://api.smile-app.co.il/v1/whatsapp/messages/in_5312 \
-H "Authorization: Bearer sk_live_..."
#Get a message's media
Mints a fresh signed link, valid for about 10 hours. 404 when the message carries no media.
curl https://api.smile-app.co.il/v1/whatsapp/messages/in_5312/media \
-H "Authorization: Bearer sk_live_..."
{
"data": {
"url": "https://s3.eu-central-1.amazonaws.com/...",
"expires_at": "2026-08-16T01:27:11+03:00"
}
}
Fetch the link when you are about to use it. Links expire, so storing one is storing something that will stop working.
#A patient's messages
curl https://api.smile-app.co.il/v1/patients/9021/whatsapp/messages \
-H "Authorization: Bearer sk_live_..."
Matched on the patient's phone number. A patient with no phone on file returns an empty page rather than a 404.
#Send a message
Requires the whatsapp:write scope, which is never bundled with whatsapp:read - this endpoint writes to a patient's phone in the clinic's name.
Free text:
curl -X POST https://api.smile-app.co.il/v1/whatsapp/messages \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "to": "0501234567", "text": "Running late? Let us know." }'
A template (see Templates):
curl -X POST https://api.smile-app.co.il/v1/whatsapp/messages \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "to": "0501234567", "template": "appointment_reminder", "params": ["Dana", "Thursday 10:00"] }'
An image, a PDF or a video, fetched from a URL you host:
curl -X POST https://api.smile-app.co.il/v1/whatsapp/messages \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "to": "0501234567", "media": { "type": "document", "url": "https://files.example.com/price-list.pdf?X-Amz-Signature=...", "filename": "Price list.pdf" } }'
| Field | Description |
|---|---|
to | Recipient phone. Separators are ignored. |
from | The clinic number to send from - a phone from Numbers. Omit it to send from the default number. An unknown number is refused with 400. |
text | Free-text body. |
template | Template name from Templates. |
params | Positional template parameters - params[0] fills {{1}}. The count must equal the template's parameter_count. |
button_param | The end of the template's link button, for a button like https://meet.google.com/{{1}} - send abc-defg-hij, not the whole link. Required when the template's requires_button_param is true. |
media.type | image (JPEG or PNG), document (PDF) or video (MP4 or 3GP - WhatsApp plays no other video format, so a phone's .mov is refused). |
media.url | An https URL SmileCloud downloads while handling the request - a presigned link valid for a few minutes is enough. Up to 16 MB. |
media.filename | Documents: the name the patient sees. Defaults to the URL's file name; .pdf is added when missing. |
media.caption | Up to 1024 characters, sent as a text message right after the media. |
Send exactly one of text, template or media.
Reply on the number the patient wrote to. A conversation's clinic_phone is the line the patient knows; pass it as from and the reply lands in the same thread on their handset. Sending from another number opens a new thread there, and its 24-hour window is that thread's, not the one the patient's message opened.
Media goes out the way a file attached in the SmileCloud chat does. SmileCloud keeps its own copy, so the message's media stays readable through GET /v1/whatsapp/messages/{id}/media after your link expires, and sends it as the clinic's image, document or video template - valid inside the 24-hour window or not, and always reported as delivery_mode: template. The template's body is fixed, which is why a caption follows as its own text message, subject to the window like any free text. The response describes the media message; the caption's id and delivery mode are under meta.caption. A file that is not the declared type, too large, or not downloadable is refused with 400 before anything is sent.
All three shapes return 202 Accepted, never 200:
{
"data": { "id": "out_8842", "status": "queued", "direction": "outbound", "...": "..." },
"meta": { "delivery_mode": "free_text" }
}
delivery_mode | Meaning |
|---|---|
free_text | Sent as free text, inside the 24-hour window. |
template_fallback | The window was closed, so your text went out wrapped in a marketing template. Billed as marketing. |
template | A template you asked for by name, or media. |
202 means accepted, not delivered
The message has been handed to WhatsApp; delivery is reported later. The returned status is queued. Subscribe to whatsapp.message.sent / .delivered / .read / .failed to be told as each receipt arrives, or re-read the message id to watch the status move.
#React to a message
Requires the whatsapp:write scope. Sets or replaces the clinic's reaction on a message in either direction; "emoji": null withdraws it.
curl -X POST https://api.smile-app.co.il/v1/whatsapp/messages/in_5312/reaction \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "emoji": "👍" }'
Returns 200 with the message, its reactions.clinic already updated. WhatsApp accepts some reactions and then drops them without telling the sender, so those are refused up front with 400:
- the message is more than 30 days old;
- the patient has not written in the last 24 hours - a reaction is a free-form message and needs the window open, like free text.
#Close or reopen a conversation
Requires the whatsapp:write scope. Sets the thread's is_handled flag - the same "handled" toggle staff use in the SmileCloud inbox. "handled": true closes the conversation, "handled": false reopens it.
curl -X POST https://api.smile-app.co.il/v1/whatsapp/conversations/812/handled \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "handled": true }'
Returns 200 with the conversation, is_handled already updated. handled must be a JSON boolean. Returns 400 when the clinic has not turned on handled-marking in its WhatsApp settings, and 404 for an unknown conversation id.
#Which templates can you send?
Only templates whose active version WhatsApp has approved, and which are not bound to an internal record. Most reminder templates fill their placeholders from an appointment or a patient inside SmileCloud, and this API does not accept those record ids - Templates marks them sendable: false with a not_sendable_reason rather than hiding them.
Sending an unsendable or unknown template returns 400, with different messages for the two cases so a correct name never looks like a typo.
#Tags
Tags are the colored labels staff put on conversations in the SmileCloud inbox - "new lead", "waiting for x-ray", "VIP". They are shared across the clinic, and a conversation can carry any number of them. Changes made through the API show up live in the inbox.
| Field | Type | Description |
|---|---|---|
id | string | Unique tag id. |
name | string | Up to 30 characters, unique within the clinic. |
color | string | #RRGGBB hex, unique within the clinic. |
#List tags
GET /v1/whatsapp/tags — scope: whatsapp:read
curl https://api.smile-app.co.il/v1/whatsapp/tags \
-H "Authorization: Bearer sk_live_..."
{
"data": [
{ "id": "3", "name": "New lead", "color": "#4CAF50" },
{ "id": "7", "name": "VIP", "color": "#FFC107" }
]
}
#Create a tag
POST /v1/whatsapp/tags — scope: whatsapp_tags:write
curl -X POST https://api.smile-app.co.il/v1/whatsapp/tags \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "name": "Website lead", "color": "#2196F3" }'
Returns 201 with the tag. Both fields are required. A name or color another tag already uses returns 400 - list the tags first and reuse the one that exists.
#Tag or untag a conversation
POST /v1/whatsapp/conversations/{id}/tags — scope: whatsapp_tags:write
add attaches tags, remove detaches them; send either or both. Tags the conversation already has, or never had, are left as they are, so the call is safe to retry.
curl -X POST https://api.smile-app.co.il/v1/whatsapp/conversations/812/tags \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "add": ["3"], "remove": ["7"] }'
| Field | Description |
|---|---|
add | Tag ids to attach. |
remove | Tag ids to detach. An id in both lists ends up detached. |
Returns 200 with the conversation, tags already updated. An unknown tag id returns 400, and an unknown conversation id 404.
#Templates
GET /v1/whatsapp/templates
The clinic's message templates. Requires whatsapp:read. Use name as the template on POST /v1/whatsapp/messages.
| Field | Type | Description |
|---|---|---|
name | string | The identifier you send. |
display_name | string | null | Human-readable label as configured in SmileCloud. |
language | string | null | Template language code. |
model_type | string | null | What the template attaches to. null or wa_chat_preview means it needs nothing but a phone number. |
category | string | null | WhatsApp's billing category, e.g. UTILITY or MARKETING. |
status | string | null | WhatsApp's review state. Only APPROVED templates can be sent. |
rejection_reason | string | null | Why WhatsApp rejected it, when it did. |
parameter_count | integer | null | How many {{n}} placeholders the body has - the exact length params must be. |
body | string | null | The template body, placeholders included. |
header, footer, buttons | mixed | null | The rest of the template as approved. |
components | object[] | The whole template as Components, placeholders kept - the shape a sent message's components takes once filled in. |
requires_button_param | boolean | The template has a link button whose end is set per send - pass it as button_param. |
sendable | boolean | Whether this API can send it. |
not_sendable_reason | string | null | Why not, when sendable is false. |
Pass ?sendable=true to list only what you can actually send. Templates are approved per WhatsApp Business account, so a clinic on several numbers may have a different catalog on each: pass ?from= with a phone from Numbers to list that number's, otherwise you get the default number's.
curl "https://api.smile-app.co.il/v1/whatsapp/templates?sendable=true" \
-H "Authorization: Bearer sk_live_..."
{
"data": [
{
"name": "appointment_reminder",
"display_name": "Appointment reminder",
"category": "UTILITY",
"status": "APPROVED",
"parameter_count": 2,
"body": "Hi {{1}}, this is a reminder for your appointment on {{2}}.",
"sendable": true,
"not_sendable_reason": null
}
]
}
Unsendable templates are still listed
Most reminder templates fill their placeholders from an appointment or a patient record inside SmileCloud, and this API does not accept those internal ids - they come back sendable: false with a reason rather than being hidden, so a template you configured never silently disappears from the list.
#Numbers
GET /v1/whatsapp/numbers
The WhatsApp numbers the clinic runs. Requires whatsapp:read.
curl https://api.smile-app.co.il/v1/whatsapp/numbers \
-H "Authorization: Bearer sk_live_..."
{
"data": [
{ "phone": "972501234567", "display_name": "Smile Dental", "is_default": true, "branch_ids": ["1", "2"] },
{ "phone": "972549876543", "display_name": "Smile Dental North", "is_default": false, "branch_ids": ["3"] }
]
}
| Field | Type | Description |
|---|---|---|
phone | string | The number, exactly as conversations and messages carry it in clinic_phone and as from accepts it. |
display_name | string | null | The business name patients see on this number. |
is_default | boolean | The number a send without from goes out on. |
branch_ids | string[] | The branches that run this number. Several branches can share one. |
The number is the thing to key on. Branches are how the clinic configures its lines, and more than one branch can sit behind the same number, so a branch id does not pick a line - phone does.
#Related
- Calls - the phone log, same phone-matching behavior.
- Scopes
- Pagination
- Errors