Send SMS through your own HTTP API

This guide explains how to send the verification codes of Casdoor through an SMS gateway that has no built-in type. Casdoor calls an HTTP endpoint that you describe, so any SMS API that accepts a plain HTTP request works.

---

Learning outcomes

• Describe the HTTP request of your SMS gateway in Casdoor.
• Understand how Casdoor builds the request.

What you need

• An SMS gateway with an HTTP API
• Administrator access to the Casdoor admin console

---

Add the provider in Casdoor

1. In the Casdoor admin console, go to Identity > Providers and add a provider.

2. Set Category to SMS and Type to Custom HTTP SMS.

3. Fill in the fields:

   Casdoor field	Meaning	Requis
   Code de modèle	Message template. The verification code replaces the %s placeholder (e.g. Your code is %s). If left empty, the raw code is sent.	Non
   Point de terminaison	The SMS API URL. Supports the {mobile} and {code} placeholders, which are replaced with the phone number and code.	Oui
   Méthode	HTTP method: GET, POST, PUT, or DELETE.	Oui
   Type de contenu	Request body encoding for non-GET methods: application/x-www-form-urlencoded (default) or application/json.	Non
   En-tête HTTP	Extra request headers (e.g. an Authorization header for your API key).	Non
   Mapping du corps HTTP	Field names used in the request for phoneNumber and content (non-GET methods).	Non
   Paramètre	The field name that carries the message content. Takes precedence over the content value in HTTP body mapping.	Non
   Activer le proxy	Send the request through the SOCKS5 proxy configured in Casdoor. See overview.	Non

4. Save the provider.

How Casdoor builds the request

• Content: The message is the Template code with %s replaced by the verification code. With an empty Template code, Casdoor sends the code alone.
• Field names: The phone number goes in the field phoneNumber, and the content goes in the field that Parameter names. You can rename both in HTTP body mapping. If Parameter is set, it takes precedence over a mapping of content.
• POST, PUT, and DELETE: Casdoor sends the phone number and the content in the body, in the selected Content type.
• GET: Casdoor appends the phone number and the content as query parameters. If the Endpoint contains the placeholder {mobile} or {code}, Casdoor fills in the placeholders and adds no query parameters.

Examples

A gateway that accepts a POST form with the fields to and text:

Field	Value
Endpoint	https://sms.example.com/api/send
Method	POST
Content type	application/x-www-form-urlencoded
HTTP header	Authorization: Bearer <your-token>
HTTP body mapping	phoneNumber to to
Parameter	text
Template code	Your verification code is %s

A gateway that takes everything in the URL with GET:

Field	Value
Endpoint	https://sms.example.com/send?mobile={mobile}&code={code}
Method	GET

Verify the result

Enter a phone number in SMS Test and send a test message.

See also

• SMS providers
• Custom HTTP notification provider