Send Phone Message
If you want to extend Auth0, we highly recommend you use Actions, which are a cornerstone of our overall extensibility product. With Actions, you have access to rich type information, inline documentation, and public npm packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read Understand How Auth0 Actions Work.
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.
The triggerId for Send Phone Message extensibility point is send-phone-message. To learn how to create Hooks for this extensibility point, see Create Hooks.
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} context.client.name - 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} context.user.name - user's name
@param {string} context.user.email - 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?
The callback function (cb) at the end of the sample code signals completion and must be included.
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": "example.us.auth0.com",
"user_agent": "Mozilla/5.0",
"client": {
"client_id": "1235",
"name": "Test Application",
"client_metadata": { }
},
"user": {
"user_id": "auth0|test12345",
"name": "Billie Magnusson",
"email": "billie@email.com",
"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.
Executing the code using the runner requires a save, which means that the original code will be overwritten.
When you run a Hook based on the starter code, the response object is:
{
"MessageID": "998a9ad1-c9b9-4b85-97b1-ac0305aa5532"
}Was this helpful?
Localization
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_localesparameter. 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: