Notion and Twilio connect through the Notion REST API combined with a polling or scheduled trigger layer, since Notion does not provide native real-time webhooks, letting you detect new or updated database pages and dispatch SMS notifications to team members or external contacts listed in your database. This integration is used by teams that track project pipelines, content calendars, or client records in Notion and want SMS alerts when a page status changes or a new entry is added without relying on manual Notion notification checks. The architecture uses scheduled polling of the Notion Databases query endpoint, a comparison against a last-processed timestamp or page ID stored in your system, and the Twilio Messages API to send the notification when a relevant change is detected.
What You Need Before You Start
Create a Notion integration at https://www.notion.so/my-integrations, give it a name, select the workspace, and copy the Internal Integration Token displayed after creation, which you will use as the Bearer token in all Notion API requests. Share each Notion database you want to monitor with your integration by opening the database in Notion, clicking the three-dot menu, then Add connections, and selecting your integration name, as the API will return a 404 for any database not explicitly shared. Your Notion API base URL is https://api.notion.com/v1/ and you must include the header Notion-Version: 2022-06-28 alongside the Authorization: Bearer {token} header on every request. From Twilio, gather your Account SID, Auth Token, and an SMS-capable phone number, and confirm your Notion database has a Phone Number property type for the contact to receive the alert and a Status or Select property you will use as the trigger condition.
Step-by-Step Integration Guide
Set up a scheduled job that runs every 5 minutes and queries your Notion database by calling POST https://api.notion.com/v1/databases/{databaseId}/query with a filter body such as filter.property set to your Status property name, filter.select.equals set to your trigger value like Ready for Review, and sort.timestamp set to last_edited_time with direction descending to get the most recently changed pages first. In the response, parse the results array and check each page's last_edited_time against your stored last-run timestamp to identify only newly changed pages since the previous poll cycle, then store the current UTC time as the new last-run timestamp in your database or cache before processing. For each new matching page, extract the phone number from the page's properties by accessing properties.Phone.phone_number or properties.Phone.rich_text[0].plain_text depending on whether you used the Phone Number property type or a plain text field, then call POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json with To set to the E.164 phone number and Body set to a message including the page title extracted from properties.Name.title[0].plain_text. After sending the SMS, update the Notion page to record that the notification was sent by calling PATCH https://api.notion.com/v1/pages/{pageId} with a properties body setting a Notified checkbox property to true, preventing the same page from triggering duplicate notifications on subsequent poll cycles.
Common Issues and How to Fix Them
The Notion API returns a 404 Not Found error for a database ID you know exists when the integration has not been explicitly shared with that database in the Notion UI. Every database must be individually connected to the integration through the Share menu even if the integration has access to the workspace, and this is the most common error when first building a Notion API integration. The polling approach creates a race condition when multiple pages are updated within the same 5-minute window and your comparator only checks the most recent edit time, causing some updated pages to be skipped. Store a set of processed page IDs in a persistent cache keyed by page ID and last_edited_time rather than relying solely on a time window, so every unique page change is processed exactly once even if several happen in quick succession. Notion's filter API does not support filtering by last_edited_time directly as a filter condition, only as a sort field, meaning your query always returns the full matching result set sorted by recency rather than only pages updated after a specific time. Manage this by storing the IDs of pages you have already notified in a Redis set or a database table, and checking each result page against that set before sending, adding newly processed IDs and removing IDs for pages that no longer match the filter condition.
How to Get More from This Integration
Build a content publication notification system by monitoring a Notion content calendar database for pages whose Publish Date property equals today and Status property equals Approved, then sending an SMS to the assigned writer's phone reminding them the article goes live today, retrieved from a linked Person property via the Notion Users API at GET https://api.notion.com/v1/users/{userId}. Use Notion's database relations to follow linked page references and retrieve contact phone numbers from a separate Contacts database rather than storing phone numbers directly on every page, keeping your database schema clean and centralized. Extend the integration to create new Notion pages from inbound Twilio SMS by building a Twilio inbound webhook handler that calls POST https://api.notion.com/v1/pages with a body containing parent.database_id set to your target database ID and properties containing the message text mapped to a Title property and the sender phone number mapped to a Phone property. Set up a two-way confirmation loop where your middleware updates a Notion page Status property to Confirmed via PATCH https://api.notion.com/v1/pages/{pageId} when a contact replies YES to an SMS, giving your team a visual status indicator in the Notion database without manually checking responses.
Conclusion
Notion and Twilio together bridge your team's knowledge workspace with direct SMS communication, keeping the right people informed whenever your database data changes. Get in touch with Telphi Consulting to build and schedule this integration for your Notion workspace.
Ready to Transform Your Business Communications?
Get a free consultation with our VoIP experts and discover how we can help you save costs, improve efficiency, and scale your business.
Comments (0)
Join the discussion and share your thoughts (AI-moderated for quality)
Be the first to comment
No comments yet. Share your thoughts below.