SmileCloudDocs

WhatsApp

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.

FieldTypeDescription
idstringUnique conversation id.
display_namestring | nullThe patient's WhatsApp profile name.
patient_phonestring | nullThe patient's number, in local 0… form.
clinic_phonestring | nullThe 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_previewstring | nullText of the most recent message.
last_activity_atstring | nullISO 8601 timestamp of the last message either way.
last_inbound_atstring | nullISO 8601 timestamp of the last message from the patient.
last_outbound_atstring | nullISO 8601 timestamp of the last message to the patient.
is_handledbooleanWhether staff marked the thread as dealt with.
free_text_window_expires_atstring | nullWhen the 24-hour free-text window closes. null means it is already closed.
patientsobject[]Patient summaries linked to the thread.
tagsobject[]The tags staff or an integration put on the thread - { "id", "name", "color" }.
created_atstring | nullISO 8601 timestamp.
updated_atstring | nullISO 8601 timestamp.

#The message object

FieldTypeDescription
idstringPrefixed id - in_… for inbound, out_… for outbound.
conversation_idstring | nullThe thread this belongs to.
directionstringinbound or outbound.
typestringtext, image, document, audio, video, sticker, contacts.
statusstringreceived for inbound. For outbound: queued, sent, delivered, read or failed.
from_phonestring | nullSender, as stored (outbound uses the international 972… form).
to_phonestring | nullRecipient, as stored.
patient_phonestring | nullThe patient side, whichever direction the message ran, in local 0… form.
clinic_phonestring | nullThe clinic side, whichever direction - the number this message ran on, as Numbers lists it.
textstring | nullMessage body, or the caption for a media message.
mediaobject{ "available": boolean, "type": string | null } - fetch the link separately.
transcriptobject | nullInbound voice notes only - see below. null for every other message.
patientsobject[]Patient summaries matched on patient_phone.
templatestring | nullOutbound only: the approved template this went out as, if any.
componentsobject[] | nullOutbound only: what the patient was shown - header, body, footer and buttons. See Components. null for inbound.
replied_to_idstring | nullInbound only: the outbound message this replies to.
reactionsobject{ "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_reasonstring | nullOutbound only: why Meta rejected it.
timestampsobject | nullOutbound only - see below. null for inbound.
created_atstring | nullISO 8601 timestamp.
updated_atstring | nullISO 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.

FieldTypeDescription
statusstring | nullprocessing, done, failed, or null when transcription was never attempted (AI features off, or the note arrived before they were turned on).
textstring | nullWhat 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)

FieldTypeDescription
sent_atstring | nullAccepted by WhatsApp.
delivered_atstring | nullReached the patient's handset.
read_atstring | nullOpened by the patient. Never set if they disabled read receipts.
failed_atstring | nullDelivery 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.

typeFields
headerformat: text with text, or image / video / document with media_id - fetch it with Get a message's media (null on a template).
bodytext. On a sent message, the words as delivered; on a template, with its {{n}} placeholders.
footertext.
buttonsbuttons: 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.
json
"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

bash
curl "https://api.smile-app.co.il/v1/whatsapp/conversations?limit=20" \
  -H "Authorization: Bearer sk_live_..."
ParameterDescription
phoneOnly the thread for this number. Separators are ignored.
clinic_phoneOnly threads on this clinic number. Separators are ignored.
is_handledtrue or false.
updated_sinceISO 8601. Switches to ascending mutation order for incremental sync.
limit, cursorSee Pagination.

Threads come back most-recent-activity first, unless updated_since is set.

#Get a conversation

bash
curl https://api.smile-app.co.il/v1/whatsapp/conversations/318 \
  -H "Authorization: Bearer sk_live_..."

#List messages in a conversation

bash
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.

bash
curl "https://api.smile-app.co.il/v1/whatsapp/messages?direction=inbound&from=2026-08-01" \
  -H "Authorization: Bearer sk_live_..."
ParameterDescription
directioninbound or outbound.
typetext, image, document, audio, video, sticker, contacts.
phoneMessages to or from this number. Separators are ignored.
clinic_phoneMessages that ran on this clinic number, either direction. Separators are ignored.
from, toISO 8601 bounds on the message timestamp.
updated_sinceISO 8601. Use this to catch delivery receipts on older messages.
limit, cursorSee 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

bash
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.

bash
curl https://api.smile-app.co.il/v1/whatsapp/messages/in_5312/media \
  -H "Authorization: Bearer sk_live_..."
json
{
  "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

bash
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:

bash
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):

bash
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:

bash
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" } }'
FieldDescription
toRecipient phone. Separators are ignored.
fromThe clinic number to send from - a phone from Numbers. Omit it to send from the default number. An unknown number is refused with 400.
textFree-text body.
templateTemplate name from Templates.
paramsPositional template parameters - params[0] fills {{1}}. The count must equal the template's parameter_count.
button_paramThe 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.typeimage (JPEG or PNG), document (PDF) or video (MP4 or 3GP - WhatsApp plays no other video format, so a phone's .mov is refused).
media.urlAn https URL SmileCloud downloads while handling the request - a presigned link valid for a few minutes is enough. Up to 16 MB.
media.filenameDocuments: the name the patient sees. Defaults to the URL's file name; .pdf is added when missing.
media.captionUp 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:

json
{
  "data": { "id": "out_8842", "status": "queued", "direction": "outbound", "...": "..." },
  "meta": { "delivery_mode": "free_text" }
}
delivery_modeMeaning
free_textSent as free text, inside the 24-hour window.
template_fallbackThe window was closed, so your text went out wrapped in a marketing template. Billed as marketing.
templateA 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.

bash
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.

bash
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.

FieldTypeDescription
idstringUnique tag id.
namestringUp to 30 characters, unique within the clinic.
colorstring#RRGGBB hex, unique within the clinic.

#List tags

GET /v1/whatsapp/tags — scope: whatsapp:read

bash
curl https://api.smile-app.co.il/v1/whatsapp/tags \
  -H "Authorization: Bearer sk_live_..."
json
{
  "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

bash
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.

bash
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"] }'
FieldDescription
addTag ids to attach.
removeTag 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.

FieldTypeDescription
namestringThe identifier you send.
display_namestring | nullHuman-readable label as configured in SmileCloud.
languagestring | nullTemplate language code.
model_typestring | nullWhat the template attaches to. null or wa_chat_preview means it needs nothing but a phone number.
categorystring | nullWhatsApp's billing category, e.g. UTILITY or MARKETING.
statusstring | nullWhatsApp's review state. Only APPROVED templates can be sent.
rejection_reasonstring | nullWhy WhatsApp rejected it, when it did.
parameter_countinteger | nullHow many {{n}} placeholders the body has - the exact length params must be.
bodystring | nullThe template body, placeholders included.
header, footer, buttonsmixed | nullThe rest of the template as approved.
componentsobject[]The whole template as Components, placeholders kept - the shape a sent message's components takes once filled in.
requires_button_parambooleanThe template has a link button whose end is set per send - pass it as button_param.
sendablebooleanWhether this API can send it.
not_sendable_reasonstring | nullWhy 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.

bash
curl "https://api.smile-app.co.il/v1/whatsapp/templates?sendable=true" \
  -H "Authorization: Bearer sk_live_..."
json
{
  "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.

bash
curl https://api.smile-app.co.il/v1/whatsapp/numbers \
  -H "Authorization: Bearer sk_live_..."
json
{
  "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"] }
  ]
}
FieldTypeDescription
phonestringThe number, exactly as conversations and messages carry it in clinic_phone and as from accepts it.
display_namestring | nullThe business name patients see on this number.
is_defaultbooleanThe number a send without from goes out on.
branch_idsstring[]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.