> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.clinicea.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 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
* Twilio Account SID and Auth Token (from Twilio Console).
* A Twilio phone number that supports SMS (e.g. +17873040275).
* Clinicea SuperAdmin / Tools access (to save integration).
* Clinicea webhook URL (example format): https://api.clinicea.com/api/v3/twilio/handleIncomingSMS?apiKey=YOUR_API_KEY&headClinicID=HEADCLINIC_GUID

## 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.
![](https://storage.crisp.chat/users/helpdesk/website/-/f/c/5/7/fc576fc9d2f46000/image_1g49npf.png)

1. Under Messaging find 'A message comes in'.
2. Set it to Webhook and paste your Clinicea URL (full URL with apiKey & headClinicID).
![](https://storage.crisp.chat/users/helpdesk/website/-/f/c/5/7/fc576fc9d2f46000/image_1dx4c1h.png)
![](https://storage.crisp.chat/users/helpdesk/website/-/f/c/5/7/fc576fc9d2f46000/image_e337h3.png)

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).
![](https://storage.crisp.chat/users/helpdesk/website/-/f/c/5/7/fc576fc9d2f46000/image_1lmdytb.png)
![](https://storage.crisp.chat/users/helpdesk/website/-/f/c/5/7/fc576fc9d2f46000/image_7efys6.png)

1. Turn Allow sending SMS to International Numbers = Yes if needed.
2. Click Save.
![](https://storage.crisp.chat/users/helpdesk/website/-/f/c/5/7/fc576fc9d2f46000/image_1gsjdi9.png)

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).
4. 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.