Skip to main content

Portal-Twilio

Portal-Twilio Guide

QA avatar
Written by QA
Updated this week

Connect Twilio to Portal (Staff Guide)

A concise, step‑by‑step guide to connect Twilio to Portal so you can deliver PINs via SMS as an alternative to email.

What you need

  • A Portal account with access to Settings → Customization and the Apps tab.

  • A Twilio account with a confirmed, SMS‑capable Twilio phone number.

  • Your Twilio Account SID and Auth Token (from the Twilio Console).

PINs sent by SMS supplement email delivery; if Twilio isn’t connected, guests receive email only.

Quick Start

  1. Enable SMS notifications in Portal

    Go to Settings → Customization → Key Notifications and ensure SMS is enabled.

  2. Open the Apps section

    From Settings → Customization, click the info icon near SMS and choose Show Apps, or go directly to the Apps tab and search for Twilio.

  3. Configure Twilio

    In Apps → Twilio, click View Integration and enter:

    • Account SID

    • Auth Token

    • Twilio phone number (E.164 format, e.g., +15551234567)

      Click Save to connect.

  4. Confirm connection

    After saving, the integration should show Connected once validation succeeds.

Templates (Portal → Apps → Twilio → Templates)

  • In your Twilio account, create a template named key_is_ready to enable SMS for the Key is ready event.

  • Supported events shown in Portal: Key is ready., Doorcode is changed.

  • Available variables you can use in your Twilio template body:

    • firstName

    • lastName

    • property

    • referenceNumbers

    • startTime

    • endTime

    • doorcode

    • keycard

    • spaces

    • devices

  • After creating or updating your template in Twilio, open Portal → Apps → Twilio → Templates and click Sync Templates to pull the latest template definitions.

  • When synced successfully, the events will show as enabled and SMS will send using your template.

Expected Behavior

  • When a PIN is created or updated, Portal sends an SMS via your Twilio number (for guests with valid mobile numbers).

  • Delivery timing: allow up to ~1 minute end‑to‑end; timestamps follow the Portal timezone.

  • If Twilio is not connected, guests continue to receive email notifications only.

Edge Cases & Errors

  • Invalid Account SID / Auth Token

    You’ll see an error and the integration won’t validate. Re‑check your credentials and try again.

  • Unconfirmed / non‑SMS‑capable number

    Sending will fail if the Twilio number isn’t SMS‑capable or not fully verified.

  • Recipient number format / region

    Numbers must be in E.164 format and SMS must be allowed in the destination country; regulatory rules (e.g., A2P 10DLC in the US) may apply.

  • Credentials rotated/revoked

    If the Auth Token is changed in Twilio, the Portal integration may break. Update credentials in Apps → Twilio.

Troubleshooting

No SMS is being sent.

  • Ensure Settings → Customization → Key Notifications → SMS is enabled.

  • Re‑enter Account SID, Auth Token, and verify the Twilio phone number in Apps → Twilio.

  • Confirm the guest phone number is valid and in E.164 format (includes country code).

  • Check Twilio Message Logs (Console) for statuses like failed or undelivered and the associated error.

  • Verify the Twilio number is SMS‑capable and that your account has sufficient balance.

Some regions fail but others work.

  • Review local regulations / compliance (e.g., registration requirements). Consider a region‑appropriate sender.

We changed our Auth Token.

  • Update the token in Apps → Twilio and Save to restore connectivity.

Security Best Practices

  • Treat the Auth Token like a password; never share it in chats or screenshots.

  • Rotate credentials periodically and when staff change roles.

  • Limit who can view or edit Apps → Twilio settings.

FAQs

Q: Where do I find my Account SID and Auth Token?

A: In the Twilio Console under Account > API Keys / Auth Tokens.

Q: Do I need a Messaging Service SID?

A: Not required for the basic setup above; a Twilio phone number is sufficient. (If your org uses a Messaging Service, ensure it’s configured to send SMS for your regions.)

Q: What if Twilio isn’t connected?

A: Guests receive email notifications only.

Q: When guest recive the SMS?

A: As soon as the key is issued.
​

Did this answer your question?