Skip to main content

Set Up Twilio for International SMS

By integrating Twilio, you can enable global SMS notifications and verification code delivery for your organization.

1. Use Cases for International SMS​

After completing the Twilio integration, SMS sent to non–Mainland China phone numbers will be automatically delivered via Twilio. Common use cases include:

  • Use the Send SMS node in workflow to trigger global notifications
  • Enable phone number verification in public forms to send real-time verification codes to international numbers
  • Send verification codes, invitations, and approval notifications in external portals

2. Register for Twilio​

  1. Go to: https://www.twilio.com
  2. Click Sign up to create an account
  3. Complete email and phone verification
  4. Access the console: https://console.twilio.com/
Key Concepts

  • Account SID
    Unique identifier for your Twilio account

  • API Key SID / API Secret
    Used for API authentication

  • Messaging Service SID (starts with MG)
    Used for sending standard SMS (notifications)

  • Verify Service SID (starts with VA)
    Used for sending and verifying SMS verification codes

  • Sender
    Can be a phone number or a brand name (Sender ID)

Summary:

  • Messaging Service → for notifications and alerts
  • Verify Service → for verification code sending and validation (login/registration)

3. Obtain API Key SID and Secret​

Create an API Key​

Path: Console → Develop → Go to API Keys → Create API key

Note: Set Key type to Standard.

Get SID and Secret​

After creating the API Key, you will receive the SID and Secret.

⚠️ Important: The API Secret is displayed only once. Store it securely. If lost, you must create a new key.

4. Obtain Messaging Service SID​

  1. In the Twilio Console, go to Messaging → Services
  2. Click Create Messaging Service and follow the setup steps
  3. After creation, copy the Messaging Service SID (starts with MG)

Notes

  • A Sender can be a phone number or a Sender ID (e.g., YourBrand, shown as the sender name on the recipient’s device). Multiple senders can be added to the Messaging Service Sender Pool, and Twilio will select the appropriate sender based on destination and other factors.

  • Senders added to the Messaging Service must be registered with Twilio or local carriers (e.g., 10DLC/A2P).

  • Not all countries support alphanumeric Sender IDs. Some countries (e.g., China) require a phone number as the sender.

  • In regions with registration requirements, using unregistered senders may result in delivery failure, blocking, or user complaints. Complete registration before use.

  • In regions like China, only approved phone numbers can be used as senders. Do not use unverified numbers or Sender IDs.

    SMS guidelines by country: https://www.twilio.com/en-us/guidelines/sms

5. Obtain Verify Service SID​

  1. In the Twilio Console, go to Verify → Services
  2. Click Create New, enter a service name (e.g., sms_verify), and select the verification scenario
  3. Save and copy the Verify Service SID (starts with VA)

6. Configure Twilio in HAP​

  1. In the Organization Admin Console, go to Integration → System Service
  2. Click Connect on the Twilio International SMS card
  3. Enter the following and save:
    • API Key SID
    • API Key Secret
    • Verify Service SID
    • Messaging Service SID

7. Pricing and Coverage​

  • Billing model:
    SMS charges are billed directly by Twilio. HAP does not charge for SMS usage.

  • Coverage:
    Supports SMS delivery to most countries and regions worldwide.

8. Troubleshooting: SMS Not Received​

If users cannot receive SMS after configuration, follow these steps:

  1. Check Phone Number Format
  • Ensure the number is valid (not virtual, blacklisted, or invalid range)
  • Must follow E.164 format: start with +, include country code (e.g., +852), and remove spaces
  1. Check Country/Carrier Restrictions
  • In Messaging → Settings → Geo Permissions, ensure the destination country is enabled
  • Check if the destination country requires sender registration (e.g., A2P, 10DLC)
  1. Check Messaging Service Configuration
  • Ensure at least one Active sender (number or Sender ID) is configured
  • Check spam filtering settings and reduce sensitivity if needed
  1. Check Twilio Logs

Go to Monitor → Logs → SMS Logs and filter by number or SID:

  • accepted / sent: Request accepted or sent
  • delivered: Delivered by carrier (check device-level blocking if not received)
  • failed: Failed delivery—check error codes (e.g., 30003 rate limit, 30004 invalid number, 30005 region restriction)
  1. Check Account Status and Balance
  • Ensure account status is Active
  • Ensure sufficient balance (trial accounts have limitations and may restrict certain countries)
  1. Check Verify Configuration (Verification Code Use Case)
  • In Verify → Services, ensure the sender is included in the Senders List and SMS is enabled
  • Use Send test SMS in the console to verify delivery
  1. Check Local Configuration
  • Ensure Messaging Service SID, API Key, and Secret in HAP are correct (no extra spaces)
  • Ensure the target number is not hardcoded as a test number
  1. Contact Support

If the issue persists after all checks, submit a ticket to Twilio Support.