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	Обов'язково
   Код шаблону	Message template. The verification code replaces the %s placeholder (e.g. Your code is %s). If left empty, the raw code is sent.	Ні
   Кінцева точка	The SMS API URL. Supports the {mobile} and {code} placeholders, which are replaced with the phone number and code.	Так
   Метод	HTTP method: GET, POST, PUT, or DELETE.	Так
   Тип вмісту	Request body encoding for non-GET methods: application/x-www-form-urlencoded (default) or application/json.	Ні
   Заголовок HTTP	Extra request headers (e.g. an Authorization header for your API key).	Ні
   Відображення тіла HTTP	Field names used in the request for phoneNumber and content (non-GET methods).	Ні
   Параметр	The field name that carries the message content. Takes precedence over the content value in HTTP body mapping.	Ні
   Увімкнути проксі	Send the request through the SOCKS5 proxy configured in Casdoor. See overview.	Ні

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