Integrate as an External SMS Provider

For selected partners, Provet Cloud allows a third-party gateway to send SMS messages instead of Provet Cloud’s own gateway. The third-party gateway is notified of new SMS messages via webhook, fetches the message through the REST API, and marks it as successful or failed.

Setup

The Provet Cloud team enables external SMS sending for your Provet instance.
Add a webhook with the URL where notifications about new SMS messages should be sent:

Settings > General > Integrations > Webhooks
Set up Open API access for the third party. The permission group associated with the application’s virtual user must include the following permissions:
- Patients and clients: Read/Write
- External message API: Read/Write
  - Read: Retrieve list/detail
  - Write: Mark external_sms as success/failure
- Appointments: Read/Write (for marking appointment reminders to be externally sent)

Workflow

User sends an SMS on Provet Cloud (e.g. by clicking a client phone number and using the SMS modal).
A webhook notification is sent to the URL configured in webhook settings:
```
{"external_sms_id": 123}
```

The third party fetches the SMS message using the REST API:

GET /<provet_id>/api/0.1/external_sms/123/

Response:

{
    "id": 123,
    "message": "test message",
    "phone_number": "+358401234567",
    "client_id": 2,
    "consultation_id": null,
    "patient_ids": [4],
    "created_date": "2025-02-14"
}

The third party sends the SMS.

The third party marks the SMS as successful or failed:

Successful:

POST /<provet_id>/api/0.1/external_sms/123/mark_successful/

Failed:

POST /<provet_id>/api/0.1/external_sms/123/mark_failed/

The status of SMS messages can be viewed in Provet Cloud:

Settings > Log > Client communication > SMS log
Once an SMS has been marked as successful or failed, it is no longer available through the REST API.
To list all SMS messages not yet marked as successful or failed:
```
GET /<provet_id>/api/0.1/external_sms/
```

Reminders

If a reminder has send_method: 4 (External), Provet Cloud will not send the reminder SMS and no external_sms object is created.

Appointment reminders

Appointment reminders have a send_externally field (default: false).

Set send_externally to true:

POST /<provet_id>/api/0.1/appointment_reminder/123/mark_external_sending/

When send_externally is true, Provet Cloud will not trigger SMS sending. The third party handles sending and marks it as sent:
```
POST /<provet_id>/api/0.1/appointment_reminder/123/mark_sent/
```