Skip to content

Commit 17c861b

Browse files
ramsribramsrib
authored
added docs for sms chat (#657)
1 parent 86be0d0 commit 17c861b

File tree

3 files changed

+137
-0
lines changed

3 files changed

+137
-0
lines changed

‎fern/chat/sms-chat.mdx‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
---
2+
title: SMS chat
3+
subtitle: Enable text-based conversations with assistants via SMS messaging
4+
slug: chat/sms-chat
5+
---
6+
7+
## Overview
8+
9+
Let customers chat with your Vapi assistants through SMS text messages. Perfect for businesses that want to provide AI support through familiar messaging channels.
10+
11+
**What You'll Enable:**
12+
* Text-based conversations through SMS
13+
* Automatic session management for each customer
14+
* Context-aware responses across message exchanges
15+
16+
<Warning>
17+
SMS chat requires a **10DLC-approved Twilio number**. Only customers can initiate conversations - assistants cannot send the first message.
18+
</Warning>
19+
20+
## Prerequisites
21+
22+
* A [Vapi account](https://dashboard.vapi.ai/) with an existing assistant
23+
* A **10DLC-approved Twilio phone number** (required for assistant responses)
24+
* Basic understanding of [phone number management](/phone-numbers)
25+
26+
---
27+
28+
## Setup Steps
29+
30+
<Steps>
31+
<Step title="Import your 10DLC Twilio number">
32+
Bring your approved Twilio number into Vapi so we can manage SMS messaging.
33+
34+
<Note>
35+
SMS is **enabled by default** when importing Twilio numbers.
36+
</Note>
37+
38+
See: [Import number from Twilio](/phone-numbers/import-twilio) and [Inbound SMS setup](/phone-numbers/inbound-sms)
39+
</Step>
40+
<Step title="Attach the number to an assistant">
41+
Assign the assistant that will handle SMS conversations for this number.
42+
43+
When customers text your number, they'll automatically start a chat session with this assistant.
44+
</Step>
45+
<Step title="Test the integration">
46+
Send a text message to your phone number to verify the assistant responds correctly.
47+
</Step>
48+
</Steps>
49+
50+
<Tip>
51+
View all SMS conversations in the [Session Logs](https://dashboard.vapi.ai/logs/session) page of your dashboard. Each SMS conversation creates a session where you can see the full message history and conversation flow.
52+
</Tip>
53+
54+
---
55+
56+
## How It Works
57+
58+
When a customer texts your number:
59+
60+
1. **Session Creation**: Vapi automatically creates a chat session for the customer
61+
2. **Context Management**: All messages maintain conversation context within the session
62+
3. **Response Delivery**: Assistant responses are sent back as SMS messages
63+
4. **Session Expiry**: Sessions expire after 24 hours of inactivity, then create fresh sessions for new conversations
64+
65+
```mermaid
66+
sequenceDiagram
67+
participant Customer
68+
participant Twilio
69+
participant Vapi
70+
participant Assistant
71+
72+
Customer->>Twilio: "Hi, I need help"
73+
Twilio->>Vapi: SMS webhook
74+
Vapi->>Vapi: Create/find session
75+
Vapi->>Assistant: Process message
76+
Assistant->>Vapi: Generate response
77+
Vapi->>Twilio: Send SMS response
78+
Twilio->>Customer: "Hello! How can I help?"
79+
```
80+
81+
---
82+
83+
## Session Management
84+
85+
SMS conversations use automatic session management:
86+
87+
<Tabs>
88+
<Tab title="Automatic Behavior">
89+
* **New customers**: Get a fresh session on first text
90+
* **Returning customers**: Continue existing session if under 24 hours
91+
* **Session expiry**: After 24 hours, new session created automatically
92+
* **Context preservation**: Full conversation history maintained within session
93+
</Tab>
94+
<Tab title="Manual Management">
95+
You cannot manually manage SMS sessions - they're handled automatically by Vapi's SMS infrastructure.
96+
97+
For programmatic chat with manual session control, use the [Chat API](/chat/quickstart) directly.
98+
</Tab>
99+
</Tabs>
100+
101+
---
102+
103+
## Limitations
104+
105+
<Note>
106+
**Current SMS chat limitations:**
107+
- **10DLC requirement**: Only 10DLC-approved Twilio numbers support assistant responses
108+
- **Customer-initiated**: Assistants cannot send the first message to customers
109+
- **Query tool**: Knowledge-base searches are not supported (same as Chat API)
110+
- **Twilio only**: Other SMS providers are not currently supported
111+
</Note>
112+
113+
---
114+
115+
## Next Steps
116+
117+
Enhance your SMS chat implementation:
118+
119+
* **[Chat API](/chat/quickstart)** - Understand the underlying chat technology
120+
* **[Session management](/chat/session-management)** - Learn how sessions work in detail
121+
* **[Phone number management](/phone-numbers)** - Configure advanced telephony features
122+
* **[Assistant configuration](/assistants/quickstart)** - Optimize your assistant for text conversations
123+
124+
<Tip>
125+
For the best SMS experience, configure your assistant with concise responses and clear conversation flows. SMS users expect quick, direct answers.
126+
</Tip>

‎fern/docs.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -436,6 +436,9 @@ navigation:
436436
- page: Session management
437437
path: chat/session-management.mdx
438438
icon: fa-light fa-layer-group
439+
- page: SMS chat
440+
path: chat/sms-chat.mdx
441+
icon: fa-light fa-comment-sms
439442
- page: Web widget
440443
path: chat/web-widget.mdx
441444
icon: fa-light fa-window-maximize

‎fern/phone-numbers/inbound-sms.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,3 +71,11 @@ Update your number to set `smsEnabled: true` if it was previously disabled.
7171

7272
For full endpoint details, see the [OpenAPI reference](/api-reference/openapi).
7373

74+
## Next steps
75+
76+
Now that you have inbound SMS enabled:
77+
78+
* **[SMS chat](/chat/sms-chat)** - Learn how customers can have full conversations with your assistants via SMS
79+
* **[Session management](/chat/session-management)** - Understand how SMS conversations maintain context automatically
80+
* **[Chat quickstart](/chat/quickstart)** - Explore the underlying chat technology powering SMS interactions
81+

0 commit comments

Comments
 (0)