Send Phone Message

Send Phone Message

If you decide to use SMS as a factor for Multi-factor Authentication (MFA), you can configure how you want Auth0 to send messages. To learn more, see Configure SMS and Voice Notifications for MFA.

If you select the 'Custom' SMS delivery method, you must create a Send Phone Message Hook that will let you write your own code to send the message. This allows you to use whatever SMS provider you want.

Hooks at this extensibility point are blocking (synchronous), which means they execute as part of the trigger's process and will prevent the rest of the Auth0 pipeline from running until the Hook is complete.

To learn about other extensibility points, see Extensibility Points.

Starter code and parameters

When creating a Hook executed at the Send Phone Message extensibility point, you may find the following starter code helpful. Parameters that can be passed into and used by the Hook function are listed at the top of the code sample.

@param {string} recipient - phone number
@param {string} text - message body
@param {object} context - additional authorization context
@param {string} context.message_type - 'sms' or 'voice'
@param {string} context.action - 'enrollment' or 'second-factor-authentication'
@param {string} context.language - language used by login flow
@param {string} context.code - one-time password
@param {string} context.request.ip - ip address (in IPv6 format; we suggest you use the ipaddr.js@1.9.0 library (const ipaddr=require('ipaddr.js@1.9.0')))
@param {string} context.user_agent - user agent making the authentication request
@param {object} context.client - object with details about the Auth0 application
@param {string} context.client.client_id - Auth0 application ID
@param {string} - Auth0 application name
@param {object} context.client.client_metadata - metadata from client
@param {object} context.user - object representing the user
@param {string} context.user.user_id - Auth0 user's ID
@param {string} - user's name
@param {string} - user 'semail
@param {object} context.user.app_metadata - metadata specific to user and application
@param {object} context.user.user_metadata - metadata specific to user
@param {function} cb - function (error, response)
module.exports = function(recipient, text, context, cb) {
 // TODO: Add your code here
  cb(null, {});

Was this helpful?


Example parameters

This is an example of the parameters:

  "recipient": "1-808-555-5555",
  "text": "Here is your one time password: 999111",
  "context": {
    "message_type": "sms",
    "action": "enrollment",
    "language": "en",
    "code": "123456",
    "ip": "",
    "user_agent": "Mozilla/5.0",
    "client": {
      "client_id": "1235",
      "name": "Test Application",
      "client_metadata": { }
    "user": {
      "user_id": "auth0|test12345",
      "name": "Billie Magnusson",
      "email": "",
      "app_metadata": { },
      "user_metadata": { }

Was this helpful?


Starter code response

Once you have customized the Hook code, you can test it using the runner embedded in the editor. The runner simulates a call to the Hook with the appropriate body and response.

When you run a Hook based on the starter code, the response object is:

    "MessageID": "998a9ad1-c9b9-4b85-97b1-ac0305aa5532"

Was this helpful?



The context.language parameter will always have one of the languages configured in the Tenant Settings. To learn more, read Universal Login Internationalization. Depending on how you trigger the MFA flow, we will calculate which language to use in the following different ways:

  • If you use the MFA API, we will use the Accept-Language header from the request and map it to a tenant language. If the language is not available, we will set the parameter to the tenant default language. To learn more, read Auth0 MFA API.

  • If you use the New Universal Login Experience, we will use a combination of the Accept-Language header and the ui_locales parameter. To learn more, read Universal Login Internationalization.

  • If you use the Classic Universal Login Experience, we will set the language to 'N/A'. This is a limitation that will be fixed in upcoming releases.

Messaging providers

Learn how to integrate different messaging providers in the links below:

Learn more