Skip to main content

Send SMS to your users

Ory Network comes with an HTTP based SMS delivery option that can be configured to point to any service that supports sending SMS via HTTP API, such as Twilio, Plivo, AWS SNS, or your own microservice.

Configuration​

SMS delivery can be configured through Ory Console or the Ory CLI. Follow these steps to configure SMS:

  1. Go to Authentication → SMS Configuration in the Ory Console
  2. Add the configuration for your SMS provider

Body configuration​

The body of the above snippet decodes to the following Jsonnet template:

function(ctx) {
  To: ctx.recipient,
  Body: ctx.body,
}

Fields available on the ctx object are:

  • recipient: The recipient's phone number
  • body: The message body
  • template_type: The template type, e.g. verification_code
  • template_data: The template data, e.g. { "VerificationCode": "1234", Idenity: { ... } }
  • message_type: The message type, e.g. sms
  • request_headers: A map of all HTTP request headers forwarded from the user request (see below)

Accessing request headers​

The following request headers are available via ctx.request_headers:

Accept
Accept-Encoding
Accept-Language
Content-Length
Content-Type
Origin
Priority
Referer
Sec-Ch-Ua
Sec-Ch-Ua-Mobile
Sec-Ch-Ua-Platform
Sec-Fetch-Dest
Sec-Fetch-Mode
Sec-Fetch-Site
Sec-Fetch-User
True-Client-Ip
User-Agent
X-Forwarded-Host
Ory-Base-Url-Rewrite
Ory-Base-Url-Rewrite-Token
X-Ory-Original-Host
Ory-No-Custom-Domain-Redirect
Cf-Ipcountry

Read the Jsonnet documentation to learn more about the Jsonnet templating language.

Templates​

Only the recovery_code, verification_code, and login_code templates support an SMS variant. Use the CLI to configure it:

  1. Download the Ory Identities config from your project and save it to a file:

    ## List all available workspaces
    ory list workspaces

    ## List all available projects
    ory list projects --workspace <workspace-id>

    ## Get config
    ory get identity-config --project <project-id> --workspace <workspace-id> --format yaml > identity-config.yaml

  2. Add the configuration for your custom SMTP server

    config.yml
    courier:
      templates:
        verification_code:
          valid:
            sms:
              body:
                plaintext: "base64://WW91ciB2ZXJpZmljYXRpb24gY29kZSBpczoge3sgLlZlcmlmaWNhdGlvbkNvZGUgfX0="
         login_code:
           valid:
             sms:
               body:
                 plaintext: "base64://WW91ciBsb2dpbiBjb2RlIGlzOiB7eyAuTG9naW5Db2RlIH19"

         recovery_code:
           valid:
             sms:
               body:
                 plaintext: "base64://WW91ciByZWNvdmVyeSBjb2RlIGlzOiB7eyAuUmVjb3ZlcnlDb2RlIH19CgpAe3sgLlJlcXVlc3RVUkxEb21haW4gfX0gI3t7IC5SZWNvdmVyeUNvZGUgfX0K"

  3. Update the Ory Identities configuration using the file you worked with:

    ory update identity-config --project <project-id> --workspace <workspace-id> --file updated_config.yaml