Send SMS to your users

The 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

The configuration can be done via the CLI only. Follow these steps:

Ory CLI

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

   ## List all available projects
   ory list projects
   
   ## Get config
   ory get identity-config {project-id} --format yaml > identity-config.yaml

2. Add the configuration for your custom SMTP server

   config.yml

   courier:
     channels:
       - id: sms
         type: http
         request_config:
           url: https://api.twilio.com/2010-04-01/Accounts/AXXXXXXXXXXXXXX/Messages.json # Adjust your account ID
           method: POST
           body: base64://ZnVuY3Rpb24oY3R4KSB7ClRvOiBjdHguUmVjaXBpZW50LApCb2R5OiBjdHguQm9keSwKfQ== # see below
           headers:
             Content-Type: application/x-www-form-urlencoded # defaults to application/json
           auth:
             type: basic_auth # or api_key
             config:
               user: AXXXXXXX # adjust your credentials
               password: XXXX # adjust your credentials

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

   ory update identity-config {project-id} --file updated_config.yaml

Body configuration

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

function(ctx) {
  To: ctx.Recipient,
  Body: ctx.Body,
}

All available fields on the ctx object are:

• Recipient: The recipient's phone number
• Body: The message body
• TemplateType: The template type, e.g. verification_code
• TemplateData: The template data, e.g. { "VerificationCode": "1234", Idenity: { ... } }
• MessageType: The message type, e.g. sms

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

Templates

Currently, only the verification_code template supports an SMS variant. To configure it, use the CLI:

Ory CLI

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

   ## List all available projects
   ory list projects
   
   ## Get config
   ory get identity-config {project-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: "Your verification code is: {{ .VerificationCode }}"

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

   ory update identity-config {project-id} --file updated_config.yaml