Menu

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Hosted Numbers FAQ

This product is currently in Developer Preview.

What is Hosted SMS?

Hosted SMS provides a method for customers to use Twilio’s Programmable Messaging, Functions and Studio products to send and receive messages on voice-enabled numbers they already own as part of an established voice application.

Will my current voice line be affected?

No, Hosted SMS does not affect your voice capabilities of the number. Hosted SMS only registers the number for SMS to route in and out from Twilio's platform.

What numbers can I host on Twilio for SMS?

Hosted SMS supports USA & Canada in Beta. Mobile numbers are not supported, VoIP numbers from some providers will be supported in the future.

How can I host my number?

You can initiate hosting of your number via the Twilio Console or programmatically via an API. Twilio will require the end user to complete ownership verification and LOA signature.

How do I verify I own the number I want to host?

Twilio currently provides two ways to verify ownership of a number. A phone verification call where the end-user answers the phone and passes back a security token to Twilio, or providing a copy of your phone bill.

What are the eligibility requirements to SMS enable a number?

By submitting a phone number to the Hosted SMS API or Console, the phone number will be evaluated for eligibility. Eligibility is determined by what country the number originates from and if there is SMS currently enabled for the number.

If you would like to check the eligibility before submitting the phone number, Twilio offers Lookup, a tool to see information about the number. If a number is not of type VoIP or mobile, then the number is eligible to be Hosted for SMS.

E.g. Lookup for an eligible Canada Local number

{
 "caller_name": null,
 "country_code": "CA",
 "phone_number": "+19029052034",
 "national_format": "(902) 905-2034",
 "carrier": {
   "mobile_country_code": null,
   "mobile_network_code": null,
   "name": "Iristel Inc. - ON",
   "type": "landline",
   "error_code": null
 },
 "add_ons": null,
 "url": "https://lookups.twilio.com/v1/PhoneNumbers/+19029052034?Type=carrier"
}

E.g. Lookup for an ineligible Canada number

{
 "caller_name": null,
 "country_code": "CA",
 "phone_number": "+19029052032",
 "national_format": "(902) 905-2032",
 "carrier": {
   "mobile_country_code": null,
   "mobile_network_code": null,
   "name": "Twilio - SMS-Sybase365/MMS-SVR",
   "type": "voip",
   "error_code": null
 },
 "add_ons": null,
 "url": "https://lookups.twilio.com/v1/PhoneNumbers/+19029052032?Type=carrier"
}

What information does Twilio need?

Information required to host a number with Twilio is as follows:

  • The authorized user's first and last name and Business Name, if applicable. An Authorized user is an individual who is a decision maker for the phone number.
  • The corresponding service address associated with the phone number. This must be an actual physical address (PO Boxes are not considered valid service addresses).
    • Note: All phone numbers have an address associated with them. For example, Twilio owns a desk phone and that desk phone is associated to Twilio's 375 Beale St address.
  • An email address will receive the Letter of Authorization document to be signed electronically.
  • The cc emails are optional watchers of the Authorization Document when it’s been sent out for signature and when the Authorization Document has been signed
  • A Letter of Authorization (LOA) signed by the authorized user of the number(s). The LOA will need to be completed and signed electronically and will be generated during the submission process.
    • Note: 15,000 numbers can be included on one Authorization Document (LOA).
    • Note: The information and signature on your LOA must match the authorized end user's name and service address provided by their current voice provider, and it must be signed in order for your submission to process.

Why does Twilio need this information?

Twilio is compliant with the General Data Protection Regulation and only collects Personally Identifiable Information that is mandated by the NANP SMS Registrars. Twilio keeps PII information for 90 days, depending on the requirement timeframe set for by sections of GDPR.

What are the phases to host my number?

After you submit your Hosted SMS request, the number goes through a 3-stage onboarding process:

  1. Preliminary eligibility check: Our system verifies that the number is in a valid format and from an allowed country and type.
    If the number passes this check, we create a Hosted Number entry for it in your Twilio Console in the `twilio-processing` status.
  2. SMS eligibility check: We verify that the number is not already SMS-enabled. A number that is already marked as SMS-enabled with its current provider cannot be used for Hosted SMS on Twilio. If the number is not currently SMS enabled, the Hosted Number Order will move to the `received` status.
  3. Verify Ownership: Once a number passes both eligibility checks, you will be able to browse to the number in your Hosted Numbers list in Console and place a verification call to the number.
  4. Sign an electronic LOA: After the number has been verified, you will need to create an electronic LOA that will be sent to the email address specified for signature.
  5. Enable Hosted SMS: When the eLOA is signed, the number will be moved to `carrier-processing` where the SMS registration will take place and then tested for inbound connectivity. Once the test passes, the number will be provisioned to your account.

What are the steps from start to finish to host a number for SMS in NANP?

  1. Create a new Hosted SMS to begin the order process. At this point, the number is checked for eligibility. Once the Hosted SMS has passed the eligibility check, the Hosted SMS will move into a “received” status.
    • If the eligibility check fails, your Hosted SMS Order will fail with the reason in Console and in the API (i.e., already Hosted SMS, non-supported country, VoIP/Mobile type).
  2. The next step is to verify proof of ownership of the Hosted SMS with a phone bill or with a verification call.
    • If using a phone bill to verify ownership, create a new Identity Document to be reviewed for authenticity.
    • If using a verification call, initiate the call by moving the status to `pending-verification` via the API resource instance, or initiating the call in Console on the Hosted SMS Order page.
  3. Once your Hosted SMS(s) have been verified, the Hosted SMS will have to be electronically placed on a new Letter Of Authorization (LOA).
    • The email specified on the Authorization Document will receive an email from HelloSign to electronically sign the document. The document should be signed by the end-user answering the phone number.
    • Note: If you have not already done so, create an Address object with the Friendly Name being the business and the First and Last name that of the authorized end user, decision maker on behalf of the phone number.
  4. After the Authorization Document (LOA) is signed, the Hosted SMS orders assigned to the Authorization Document will move into a “carrier-processing” status.
    • Note: landline numbers will take up to 1 business day, while Toll-Free numbers can take up to 2-3 business days.
  5. Once the number has been successfully registered for SMS with Twilio, the number will move to the testing status for a short period, to ensure inbound SMS connectivity is functional.
  6. When testing is successful, the Hosted SMS Order will move to completed and your Hosted SMS will move to in-use.
    • Note: If you would like to receive status updates on the Hosted SMS Order, you can configure a Status Callback Url.

How long does it take to message enable my number?

If using the phone verification call, from start to finish a North American Numbering Plan landline number can take up to 1 business day to message enable, test inbound connectivity, and provision to your account,

Toll-Free numbers can take up to 3 business days to update. If you are the RespOrg of the Toll-Free number, you are able to speed the request along by accepting Twilio’s request to SMS enable the toll-free number. If you are not the RespOrg, please inform your service provider to prevent any denial of Twilio’s text provisioning request.

What happens if the number moves to action-required?

When a number moves into “action-required”, a failure reason is exposed in both the Public API and in Console to help you diagnose and resolve the issue. If the issue is internal to Twilio, a `contact Hosted SMS Support` modal will be displayed in Console. If using the API, please send your Hosted SMS Order SID to HostedSMS@twilio.com for support.

Note: Friendly Names may change

  • The Letter Of Authorization was not signed within 7 days.
  • Hosted SMS Order was idly in the verification process for 7 days.
  • Hosted SMS Order has reached the maximum number of verification attempts.
  • Cannot host phone number because carrier type information is unavailable. (?)
  • The number is enabled for SMS by another provider.
  • There was a problem processing your Hosted SMS Order, Please cont HostedSMS@twilio.com.

How can I bypass my call tree to receive the verification call?

You can verify numbers behind IVRs using both the above methods by including ‘w’ characters in the Extension parameter. Each ‘w’ character tells Twilio to wait 0.5 seconds instead of playing a digit. This lets you adjust the timing of when the digits begin playing to suit the phone system you are dialing.

For example, the extension “wwww2wwwwww5wwwwww9′′ waits two seconds before sending the digit 2, followed by a three-second wait before sending the 5, and finally another three-second wait before sending a 9. You will need to tune the extension to the IVR system to be able to programmatically verify numbers behind IVR menus.

Can I use Co-Pilot or Proxy with Hosted SMS?

Yes! Hosted SMS now works with Co-Pilot/Messaging Service.

Unfortunately, Proxy does not currently work with Hosted SMS. Future integration is planned as an update to the product at a later time.

Can I use my Hosted Number as a Verified/Outgoing Caller-ID?

Yes, a Hosted Number is capable of making outbound calls over Twilio's network, as well as two-way SMS messages.

Note: if an account already has an active Verified Caller-ID and then the account requests to host the same number for SMS, the Verified Caller-ID will be deleted and the number will bypass the proof of ownership since the Verified Caller-ID already validated ownership with a two-factor authorization call.

What if I no longer want to host my number on Twilio?

If you have completed the Hosted Number Order process and would no longer want to host a number on Twilio, you can disassociate the number from Twilio by sending a DELETE request on the IncomingPhoneNumbers instance resource, or by removing the number from your account on the Hosted Number instance page in the Manage Active Numbers Console. The number will be in the released status for 3-days until the number is no longer registered to Twilio's network.

What if I made a mistake on the Authorization Document?

Please "revoke" the existing Authorization Document in Console. Once the Authorization Document has been revoked, all of the Hosted Number Orders that have been mapped to the Authorization Document will move to the `verified` status. To send out a new Authorization Document, select all verified Hosted Number Orders and bulk action create in Hosted Number Orders Console to generate a new one with the corrected information.

Can I use MMS with Hosted SMS?

USA and Canada local numbers can be hosted for SMS+MMS. USA and Canada toll-free numbers only support SMS.

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

Loading Code Sample...