Smileline
Settings

Phone system webhook

Connect a phone system Smileline has no direct connection to by sending each ringing and finished call to a signed webhook.

Use this when your practice's phone system isn't one Smileline connects to directly — a reseller's platform or a system you host yourself — but it (or whoever runs it for you) can send an HTTPS request when a call rings and when it ends. Each finished call then lands in the call log and on the patient's timeline, its recording is copied into Smileline, and missed calls are followed up, as described in Phone providers.

Calls you make stay in your own phone system: Smileline can't dial through it.

Set it up

Open Settings → Phone providers and, on the Other phone system (webhook) card, click Connect. Only the practice owner can do this.

Copy the Webhook URL and the Signing secret into your phone system, then click Done. Both are shown once: Smileline cannot show them again.

Make a test call and check it appears in the call log. Smileline answers 200 even to a URL it doesn't recognise, so a mistyped URL fails quietly.

If you lose the URL or the secret, click New URL and secret on the card. Every pair you replace keeps working for 24 hours from when you replaced it — even if you make another new pair meanwhile — so you have time to update your phone system. You can make a new pair up to ten times in 24 hours.

Sign each request

Send every request as POST with Content-Type: application/json and a JSON body of up to 256 KiB, and add two headers:

HeaderValue
X-SmileLine-TimestampThe current Unix time in seconds.
X-SmileLine-Signaturev1= followed by the hexadecimal HMAC-SHA256 digest of the signed bytes, using the signing secret as the key.

The signed bytes are the timestamp, a full stop, then the exact raw request body:

timestamp.rawBody

Sign the exact bytes you send: reformatting the JSON or adding a newline after signing makes the signature invalid. Sign each attempt as you send it — a timestamp more than five minutes away from when Smileline receives the request is refused as a possible replay.

Smileline checks the signature the moment the request arrives, so a request it has already kept is never affected by a new pair made after it. A request whose signature doesn't verify, or whose timestamp is too old, is still kept: it goes to the review queue instead of the call log.

A ringing call

Optional. Send it as the phone starts ringing, and Smileline looks the caller up — or creates the lead when nobody matches, as for a website enquiry.

{
  "type": "ring",
  "callId": "call-8812",
  "from": "+447700900123",
  "to": "+442079460123",
  "at": "2026-11-14T10:15:02Z"
}
FieldRequiredMeaning
typeYesring
callIdYesYour system's ID for the call, up to 200 characters. Use the same ID for the call's ring and its finished call.
fromYesThe caller's number, in international format (+44…).
toYesYour practice number they called.
atYesWhen it started ringing.

A finished call

Send it once the call has ended — within 48 hours of the call starting. What counts is when Smileline received it, not when it got round to processing it.

{
  "type": "completed",
  "callId": "call-8812",
  "sentAt": "2026-11-14T10:21:40Z",
  "direction": "inbound",
  "from": "+447700900123",
  "to": "+442079460123",
  "startedAt": "2026-11-14T10:15:02Z",
  "answeredAt": "2026-11-14T10:15:09Z",
  "endedAt": "2026-11-14T10:21:31Z",
  "agentEmail": "reception@example.com",
  "voicemail": false,
  "recordingUrl": "https://recordings.example.com/call-8812.mp3",
  "summary": "Asked about whitening; booked a consultation."
}
FieldRequiredMeaning
typeYescompleted
callIdYesYour system's ID for the call, up to 200 characters.
sentAtYesWhen you sent this version of the call. When you send a call more than once, the latest sentAt wins.
directionYesinbound or outbound.
fromYesWho rang: the caller for an inbound call, your practice number for an outbound one.
toYesWho was rung.
startedAtYesWhen the call started ringing.
answeredAtNoWhen someone answered. Leave it out, or send null, for a call nobody answered.
endedAtYesWhen the call ended.
agentEmailNoThe email of the person who answered (inbound) or dialled (outbound).
voicemailNotrue when the caller left a voicemail.
recordingUrlNoAn https link to the call's recording. See Recordings.
summaryNoYour system's own summary of the call.

Times are ISO 8601 with a time zone, such as 2026-11-14T10:15:02Z, and must run in order: startedAt, then answeredAt, then endedAt. A call longer than eight hours goes to the review queue. A body that is not one of these two shapes is kept in the review queue, never dropped.

Worked example

With the URL and secret in SMILELINE_WEBHOOK_URL and SMILELINE_WEBHOOK_SECRET, from a shell:

body='{"type":"ring","callId":"call-8812","from":"+447700900123","to":"+442079460123","at":"2026-11-14T10:15:02Z"}'
timestamp="$(date +%s)"
signature="$(printf '%s' "${timestamp}.${body}" | openssl dgst -sha256 -hmac "$SMILELINE_WEBHOOK_SECRET" -hex | sed 's/^.* //')"

curl -X POST "$SMILELINE_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -H "X-SmileLine-Timestamp: ${timestamp}" \
  -H "X-SmileLine-Signature: v1=${signature}" \
  --data-binary "$body"

The same in Node.js:

import { createHmac } from "node:crypto";

export async function sendToSmileline(call) {
  const body = JSON.stringify(call);
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const signature = createHmac("sha256", process.env.SMILELINE_WEBHOOK_SECRET)
    .update(`${timestamp}.${body}`)
    .digest("hex");
  const response = await fetch(process.env.SMILELINE_WEBHOOK_URL, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-SmileLine-Timestamp": timestamp,
      "X-SmileLine-Signature": `v1=${signature}`,
    },
    body,
  });
  // Anything but 200 means Smileline did not keep it: send it again later.
  if (response.status !== 200) {
    throw new Error(`Smileline answered ${response.status}`);
  }
}

Retries and corrections

Smileline stores each request before it reads it and answers in milliseconds:

  • 200 — kept. Smileline processes it a moment later.
  • 503 — not kept. Send it again after the Retry-After seconds.
  • 429 — too many requests from your address. Send it again after the Retry-After seconds.
  • 413 — the body is larger than 256 KiB.

Sending the same body again is safe: a copy of a request Smileline already has changes nothing. To correct a finished call — a recording that became available later, a fixed summary — send the whole completed body again with a later sentAt. The call is updated in place. A body whose sentAt is not later than the one Smileline holds for that call changes nothing, so corrections that arrive out of order never undo a newer one — including ones you replay from the review queue. Smileline takes up to three corrections per call on its own; a further one waits in the review queue with Try again. Once your practice's retention window for the call's transcript has passed, Smileline no longer accepts corrections to that call.

Recordings

Smileline copies the file at recordingUrl once into its own storage and plays and transcribes it from there. The link must:

  • be https on a public address, needing no login or extra headers;
  • serve the audio file itself (at most three redirects), up to 32 MiB;
  • stay fetchable for 7 days after you send it.

If the link has expired or the file can't be fetched, Smileline tries again a few times, each time with the newest finished call you sent — so sending the call again with a later sentAt and a fresh recordingUrl replaces the link. If every try fails, the call stays in the call log and the recording shows in the review queue with Retry.

Who took the call

Smileline matches agentEmail to the member of your practice with the same email address, checking again on every call: a member whose access is suspended, or who has left, is no longer credited. Each address appears under People on the card the first time it is sent; if someone uses a different address in your phone system, choose them there — a choice you make by hand always wins. A call with no match is logged without a person.

Pause, disconnect and review

The card's dropdown pauses or disconnects the webhook as for any phone provider. Anything Smileline couldn't process is listed in the review queue, with View details, Try again where it can help, Mark as handled and Delete.

On this page