Generic SMS Gateway Connector

Descope's Generic SMS Gateway connector allows you to send SMS messages using your own API. This guide walks you through setting up and using the Generic SMS Gateway connector within your Descope project.

Configure Generic SMS Gateway Connector

To integrate your SMS Gateway, you'll need your Post Message URL, authentication details, and the sender information.

1. Go to the Connectors page within the Descope Console.
2. Search for Generic SMS Gateway and select the connector tile.

Settings

Below are the required settings for configuring the Generic SMS Gateway connector:

• Connector Name: A custom name for your connector. Useful for managing multiple connectors.
• Connector Description: A brief description of this connector’s purpose.
• Post Message URL: The API endpoint where Descope will send SMS requests.
• Authentication:
  • API Key or Token: Provide the authentication method required by your SMS gateway.
  • Optional: Configure static IPs if your gateway requires fixed IP addresses for security.
• Sender:
  • A phone number or string of numbers that will appear as the sender of the SMS.

Once configured, you can test the connection using the Test button. Review the Test Results panel to verify successful integration.

Click Create to save the configuration.

SMS Payload Schema

Descope sends SMS messages to your API using the following schema. Ensure your API is set up to handle this format:

{
  "recipient": "+1 399 999",
  "body": "Your own template",
  "sender": "+1 234 567",
  "token": "Just the code itself"
}

• recipient: The phone number receiving the SMS (in international format).
• body: The content of the SMS message.
• sender: The phone number or identifier sending the message.
• token: The dynamic token/code to be sent (e.g., OTP).

Using Your Generic SMS Gateway Connector

Sending OTP/Magic Link SMS Messages

To use your Generic SMS Gateway for your OTP / Magic Link authentication method messages:

1. Navigate to Authentication Methods, and select either OTP or Magic Link.
2. Select your configured Generic SMS Gateway connector.
3. Define your OTP Template for messages.

For details on template creation, see Using Email and SMS Templates.

All OTP flows and API/SDK OTP calls will now utilize your SMS Gateway for message delivery.

Sending Custom SMS Messages

To send non-OTP/Magic Link SMS messages:

1. Open Flows and select a flow.
2. Click the + icon to add a new action.
3. Select Connector > Generic SMS Gateway.
4. In the action settings:
   • To: Recipient's phone number (e.g., {{user.phone}}).
   • Message Content: The custom message you want to send.

Link this action logically in your flow (e.g., after a user completes a specific step).

Handling Errors with the Generic SMS Gateway

If your API returns errors (e.g., invalid recipient or server issues), Descope can capture and handle these within your flows.

For example, if your API returns a "number blocked" error, you can:

1. Use Descope’s error handling features to catch the error.
2. Display a custom error message or retry the action.

For more on error handling, see Customizing Flow Errors.