Skip to main content
The SMS channel lets a VIVI agent send and receive text messages over a real phone number, either local 10DLC or toll-free. Inbound messages route to the agent like any other channel; outbound sends flow through VIVI’s consent middleware so every recipient is opted in before the agent can text them.

​
Prerequisites

SMS in the United States and Canada is regulated by the CTIA (industry body) and major carriers (AT&T, T-Mobile, Verizon). They require explicit, verifiable consent from every recipient before you send them a message. Acceptable ways to collect consent:

Web Form

A checkbox next to the phone field on your sign-up page, with disclosure text (e.g. “I agree to receive transactional texts from . Msg & data rates may apply. Reply STOP to opt out.”)

In-Person (Verbal)

The contact gives consent at point of sale or during a service interaction; staff records it in your CRM.

Reply-In (Text-to-Join)

The contact texts a keyword (e.g. JOIN) to your number first. This is the only flow that doesn’t require collection elsewhere, but is also the lowest-volume.
VIVI will not send messages for you if consent isn’t on file. The consent middleware will block the send until the recipient texts in to confirm.
You also need to know what use case you’ll be texting for. Toll-free numbers and A2P-registered local numbers are reviewed by Twilio + carriers against a declared use case. “Transactional notifications” and “customer care” are the easy approvals; marketing is allowed but requires more justification.

​
Create an SMS Channel

1

Open Channels

From the workspace sidebar, expand Agents → Channels. Hit Add New in the top-right to start.
2

Name the channel and pick SMS

Enter a Channel Name and select SMS from the Type dropdown.
The channel name is both your internal-facing label and the{brand}value rendered into consent templates (e.g. “Acme Restore” → recipients see “Reply STOP to unsubscribe from Acme Restore”). Pick your trading name, not your legal entity name.
3

Fill in the SMS-specific fields

Selecting SMS expands the modal with:

Timezone

IANA timezone (e.g. America/New_York). Used for time-of-day greetings. If left blank the agent will assume UTC is the timezone.

Enable MMS

Toggle on if you’ll send picture messages. Restricts the number search to MMS-capable numbers.

Country

Required. US, Canada, or Puerto Rico.

Number Type

Required. Enables once country is picked.
4

Choose Local or Toll-Free

Best for cross-state messaging, instant provisioning, and broad recipient reach. Throughput up to ~10 msg/sec after verification.Approval time: 1–5 business days (Twilio TFV review).
If you don’t see Local, it’s off for your workspace. Please contact your Account Admin for more details.
5

Filter and pick a number

After picking a number type, VIVI calls Twilio’s availability endpoint and shows a heads-up about compliance requirements, plus optional filters:
  • Area code — a specific US area code (e.g. 415). Skip → results span the whole country.
  • Vanity pattern — a digit sequence the number should contain (e.g. 43556 spells HELLO), with placement Anywhere, Start, or End. Letters convert to digits automatically.
Available numbers render as a grid below. Toll-free numbers include 800, 833, 844, 855, 866, 877, and 888 prefixes.
6

Reserve and save the number

Click a number to reserve it and a 60-second hold timer starts (“Number held for 46s — save now to secure it”). If you don’t click Save in time, the number releases back to Twilio’s pool.
Local 10DLC numbers are provisioned immediately at Twilio but can’t send a single message until your A2P brand and campaign are approved. Toll-free numbers can technically send low-volume test traffic during TFV review, but real production volume requires the verification to land.
Click Save. VIVI provisions the number at Twilio, persists the channel row, and lands you on the channel detail page.
7

Configure consent templates

Switch to the Consent tab on the channel detail page and fill in the three required templates (see Consent Middleware below), then click Save consent messages.
8

Submit verification (toll-free) or register A2P (local)

Toll-free: Once saved, the Compliance hub shows the channel with an Action required badge. Submit the 3-step Toll-Free Verification form.Local 10DLC: Register your A2P brand and campaign before the number can send.See the Twilio Compliance guide for the field-by-field walkthrough.

​
Conversation Sessions

SMS conversations automatically start fresh after meaningful inactivity boundaries. This keeps unrelated requests from the same phone number out of the agent’s current context and records them as separate conversations in reports. Open Conversation sessions on the SMS channel details page to use the default timing or configure custom thresholds and completion guidance. See Conversation Sessions for the timing rules, examples, and configuration steps.
Every SMS channel ships with an automated consent layer, which is the CTIA-mandated response templates VIVI’s middleware sends on your behalf. Open the channel’s Consent tab; each sub-tab has a live phone preview on the right. The {brand} placeholder renders to the channel name at send time.
There’s no separate “Opt-in” tab. The opt-in message is generated automatically the first time your agent tries to text a number with no consent record on file — it’s derived from the channel’s brand plus a CTIA-compliant default template. You only configure the three tabs below.
Sent when a user texts STOP, UNSUBSCRIBE, END, CANCEL, or QUIT.Must confirm the unsubscribe and state that no further messages will be sent.

​
How Opt-in & Opt-out Work

Every (channel × phone number) pair has a consent state in the database: UNKNOWN → WAITING_OPT_IN → OPTED_IN ⇄ OPTED_OUT.
1

Agent tries to send to a new number

State moves from UNKNOWN to WAITING_OPT_IN. VIVI sends the auto-generated opt-in template and queues the intended message in sms_message_queue with status PENDING_OPT_IN.
2

Recipient confirms

User replies YES, START, UNSTOP, or JOIN.
3

Queue drained

State → OPTED_IN. Queue status → DRAINING, then queued messages dispatch and status → SENT.

​
Compliance Summary

Twilio TFV Form

Required for toll-free only. 3-step form, 1–5 business day review.

A2P Brand & Campaign

Required for local 10DLC only.

Consent Templates

Opt-out, Resubscribe, and Help templates required for both number types.

STOP Keyword

A single opt-out keyword is required for both number types.

Double Opt-In

Strongly recommended for both — reply YES to confirm.

Identifiable Brand

Strongly recommended in every message for both number types.

​
Troubleshooting

The middleware likely queued the message instead of sending it because the recipient isn’t opted in yet. Check the sms_message_queue table for rows with phoneNumber = <recipient> and status = PENDING_OPT_IN. The recipient receives an opt-in prompt instead; when they reply YES, your message drains out automatically.
Twilio’s use case summary field has a hidden cap of 500 characters and rejects opaquely if you exceed it. The frontend enforces this with a hard maxLength and a live counter. If a pre-existing row already exceeds the cap, shorten the text before saving. See Twilio errors and use cases for canonical text patterns that pass review.
A submission for this number is already IN_REVIEW or TWILIO_APPROVED, and Twilio doesn’t allow duplicates. VIVI handles this automatically by dispatching a PATCH to the existing verification instead of POSTing a new one, or returns a “fields locked — review in progress” message. Older alerts for this error self-heal next time the user saves.
Local 10DLC numbers cannot send a single message until both your A2P brand and campaign are approved by Twilio and carriers. Check the Compliance hub — if either shows Under review, SUBMIT_FAILED, or Action required, that’s your blocker.

Twilio Compliance Guide

A2P, Toll-Free, and status flows — field-by-field walkthrough of every form.

Twilio Errors & Use Cases

Opt-in patterns, rejection reasons, and error codes.