Twilio ⇄ Clinicea SMS Integration — FAQ & Step-by-step Guide

Twilio ⇄ Clinicea SMS Integration — FAQ & Step-by-step Guide

This document describes how to integrate Twilio with Clinicea for two-way SMS.

It includes setup steps, testing procedures, troubleshooting, and screenshots for quick reference.


Saved screenshots are included below each relevant section to speed up configuration.



What is this guide for?

How to connect a Twilio phone number to Clinicea so inbound SMS reach Clinicea and Clinicea can reply (2-way SMS).


Before you start — what you need


How to set up Twilio (phone number side) — quick steps

  1. Log into Twilio Console.
  2. Go to Phone Numbers → Active Numbers → click your Twilio number.


  1. Under Messaging find 'A message comes in'.
  2. Set it to Webhook and paste your Clinicea URL (full URL with apiKey & headClinicID).


  1. Set HTTP
 POST. Save settings.
  1. If your number is attached to a Messaging Service, check the service inbound settings too.

How to set up Clinicea (app side) — quick steps
  1. In Clinicea go Tools → Organization → Integration → SMS Gateway.
  2. Choose Twilio as provider.
  3. Fill in Account SID, Auth Token, and Phone No (Twilio number).

  1. Turn Allow sending SMS to International Numbers = Yes if needed.
  2. Click Save.

  1. Open SuperAdmin page and click Save there too (important — changes take effect only after that).

One-time Twilio console extras you must check
  • Geo Permissions: Messaging → Settings → Geo Permissions and enable the destination country (e.g., Puerto Rico).
  • Phone Capabilities: In Active Numbers, check Capabilities — SMS must be allowed.
  • Trial account: If Twilio is a trial account, the destination number must be verified in Twilio.

How to test the integration (fast)
  1. From a real mobile phone, send SMS to the Twilio number.
  2. In Clinicea, open CallBox → SMS and look for the new message in the Inbox.


  1. In Twilio Console go to Monitor → Logs → Messaging and open that message.
  • Verify Request URL = your Clinicea webhook.
  • Check Request Inspector: Twilio → POST body and Clinicea → response code (200 OK).
  1. Reply from Clinicea UI and confirm that the outgoing SMS is sent and shows up in Twilio logs.

Quick curl you can use to simulate Twilio (useful for debugging)
curl -v -X POST "https://api.clinicea.com/api/v3/twilio/handleIncomingSMS?apiKey=YOUR_API_KEY&headClinicID=HEADCLINIC_GUID" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "To=+17873040275" \
  --data-urlencode "From=+1787920XXXX" \
  --data-urlencode "Body=Test+message"
Expect 200 OK from Clinicea.

 
How to check whether Twilio actually fired the webhook
  1. Twilio Console → Monitor → Logs → Messaging → open the message.
  2. In the message details look at Request Inspector: shows the POST, response status and body, retries if any.
  3. If no request is shown, Twilio didn’t receive the inbound SMS or webhook not configured.

Common error codes & what they mean
  • 21608 — Geo permission blocked for that country (enable in Geo Permissions).
  • 21408 — Account not allowed to send to that destination (billing / permission issue).
  • 30003 — Unreachable destination (carrier / number issue).
  • 30006 — Landline or unsupported destination for SMS.

If you paste the Twilio error code, I can tell you exact fix.
Troubleshooting checklist (if inbound or outbound messages fail)
  • Did you save the Twilio number settings after pasting Clinicea URL?
  • Did you save Clinicea SMS Gateway and then save SuperAdmin page?
  • Is Geo Permissions enabled for the destination country?
  • Is your Twilio number SMS-capable?
  • If trial account — is the destination number verified in Twilio?
  • Check Twilio Message Logs → Request Inspector for POST body and response code.
  • Check Clinicea server logs for the same timestamp.
  • Use the curl above to reproduce what Twilio would send.

Security & best practices
  • Don’t share Auth Token or apiKey publicly. Treat them like passwords.
  • Prefer passing API keys in an HTTP header (e.g., X-API-Key) rather than in query string if possible.
  • Consider enabling Twilio Signature verification on Clinicea (verify X-Twilio-Signature).
  • If credentials were exposed, regenerate the Auth Token and update Clinicea settings.

Quick QA test plan (minimal)
  1. Send SMS from an external phone → check Clinicea inbox.
  2. Send keyword Y → confirm Clinicea sends confirmation reply and updates appointment.
  3. Send N → confirm cancellation flow.
  4. Send CB → confirm callback request queued.
  5. Confirm every test message appears in Twilio Monitor logs with 200 OK response.
  6. Confirm outgoing replies appear as Sent/Delivered in Twilio logs.

Notes to record for future reference
  • Twilio Account SID
  • Twilio Auth Token (rotated date)
  • Twilio phone number(s) used
  • Clinicea webhook URL + API key + HeadClinicID
  • Who saved the SuperAdmin page (name & date)
  • Date when Puerto Rico (or other country) was enabled in Geo Permissions

Who to contact if things still fail
  • Check Clinicea logs and contact Clinicea support / developer (give them message time + From number).
  • If the problem looks Twilio-side (error code from logs) open a Twilio support ticket — include Message SID and Request Inspector details.
Updated on: 13/10/2025
Was this article helpful?
Share your feedback
Cancel
Thank you!