Skip to main content

Portal-Twilio

Portal-Twilio Guide

QA avatar
Written by QA
Updated over a month ago

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).

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)

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

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

  3. Portal Dashboard> Apps> Twilio> Templates, here you can customize the SMS message sent to users. Available variables you can use in your SMS template body:

    • firstName

    • lastName

    • Full Name

    • property

    • referenceNumbers

    • startTime

    • endTime

    • doorcode

    • App Link

    • Space Name

The If Exists condition displays content only when a value is available. Value should starts with {{#sec}}...and ends with{{/sec}}.

Example use cases:

  1. Show the guest’s name only if it exists

  2. Display stay dates only if start and end dates are provided

  3. Include the door code or app link only when they are ready

The If Empty condition is used as a fallback. It displays alternative text when a value is missing. Value should starts with {{^sec}}...and ends with{{/sec}}.

Example use cases:

  1. Show a generic greeting if the guest’s name is unavailable

  2. Hide sections like space name or door code if they haven’t been assigned yet

  • Staff can edit the template content and select which variables to include.

  • Staff can enter test values for selected variables to preview the final message.

  • Staff can view a live preview of the rendered message.

  • Staff can reset a customized template to its default configuration

Expected Behavior

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

  • The sms included all variables such as Reference number, Start/End date, and Door name only if the reservation comes from PMS. (First Sc)

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

  • If Twilio isn’t connected, and the guest does not have an email address, SMS will be sent with the default template.

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.

  • If the Guest has an email address, the system does not send SMS to them on the first try, only after sharing credentials.

  • 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 guests receive the SMS?

A: As soon as the key is issued.
​

Did this answer your question?