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, and send with whatsapp:write.

#Two things to know first

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 the clinic has exchanged messages with.

#The message object

#The timestamps object (outbound only)

status is derived from these, and terminal beats progress: a message that failed after WhatsApp accepted it reports failed, not sent.

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_..."

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_..."

#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"] }'

Both shapes return 202 Accepted, never 200:

{
  "data": { "id": "out_8842", "status": "queued", "direction": "outbound", "...": "..." },
  "meta": { "delivery_mode": "free_text" }
}

#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 422, with different messages for the two cases so a correct name never looks like a typo.

#Templates

GET

The clinic's message templates. Requires whatsapp:read. Use name as the template on POST /v1/whatsapp/messages.

Pass ?sendable=true to list only what you can actually send.

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
    }
  ]
}

#Related

• Calls - the phone log, same phone-matching behavior.
• Scopes
• Pagination
• Errors