Add documentation for Inbound SMS feature with Twilio (#622)

Co-authored-by: Cursor Agent <[email protected]>
Co-authored-by: sahil <[email protected]>

Author: 3 people

fern/docs.yml

@@ -310,6 +310,9 @@ navigation:
           - page: Free Vapi number
             path: phone-numbers/free-telephony.mdx
             icon: fa-light fa-gift
+          - page: Inbound SMS
+            path: phone-numbers/inbound-sms.mdx
+            icon: fa-light fa-message
           - section: Telephony integrations
             icon: fa-light fa-link
             contents:

fern/phone-numbers/inbound-sms.mdx

@@ -0,0 +1,73 @@
+---
+title: Inbound SMS
+subtitle: Let agents auto-start chats from incoming text messages (US only)
+slug: phone-numbers/inbound-sms
+---
+
+## Overview
+
+Vapi agents can automatically initiate a conversation when your number receives an inbound SMS.
+
+<Warning>
+  Inbound SMS is currently supported only for **Twilio US numbers** with **SMS enabled**, and only for **US ↔ US** messaging. Messages sent from or to non‑US numbers are not supported.
+</Warning>
+
+When enabled, Vapi configures the Twilio Messaging webhook on your number so inbound texts start a session with your agent.
+
+<Tip>
+  Prefer a walkthrough? Watch the video guide: [Inbound SMS with Vapi](https://www.youtube.com/watch?v=NCf9Q-z-xUk)
+</Tip>
+
+## Requirements
+
+- **Twilio number in the US**
+- **SMS capability enabled** on that number (in Twilio and in Vapi)
+- **US-to-US** messaging only
+
+## Set up from the dashboard
+
+<Steps>
+  <Step title="Import your Twilio number">
+    Bring your number into Vapi so we can manage voice and messaging webhooks.
+    
+    See: [Import number from Twilio](/phone-numbers/import-twilio)
+  </Step>
+  <Step title="Enable SMS for the number">
+    In the number settings, turn on the **SMS** option. Vapi will set the Twilio Messaging webhook to route inbound texts to your agent.
+  </Step>
+  <Step title="Attach your agent (optional)">
+    Assign the assistant you want handling conversations for this number. Inbound texts will start a session with that assistant.
+  </Step>
+</Steps>
+
+## Set up via API
+
+You can enable inbound SMS while creating or updating a Twilio phone number by setting `smsEnabled: true`.
+
+### Create or import a Twilio number with SMS enabled
+
+<EndpointRequestSnippet endpoint='POST /phone-number' />
+
+Key fields:
+
+- **provider**: `twilio`
+- **smsEnabled**: `true` (lets Vapi manage Twilio Messaging webhooks)
+
+<ParamField path="smsEnabled" type="boolean" default="true">
+  Controls whether Vapi configures the Twilio Messaging webhook during import/creation. If `false`, Vapi leaves your Twilio messaging URL unchanged.
+</ParamField>
+
+### Enable SMS on an existing number
+
+<EndpointRequestSnippet endpoint='PATCH /phone-number/{id}' />
+
+Update your number to set `smsEnabled: true` if it was previously disabled.
+
+## Notes and limitations
+
+- **US-only**: Both sender and recipient must be US numbers.
+- **Twilio only**: Other telephony providers are not supported for inbound SMS at this time.
+- **Webhooks**: With `smsEnabled: true`, Vapi manages the Twilio Messaging webhook for you.
+
+For full endpoint details, see the [OpenAPI reference](/api-reference/openapi).
+