Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vivi.bot/llms.txt

Use this file to discover all available pages before exploring further.

The SMS channel lets your VIVI agent send and receive text messages with end-users over a phone number you provision through VIVI. SMS conversations are 1-to-1 (one number ↔ one recipient at a time) and run on Twilio’s messaging network.

​
Prerequisites

Before you create an SMS channel, you must already have explicit consent from every recipient that their phone number can be used to receive automated messages from your VIVI agent. VIVI’s middleware then adds a second confirmation prompt on top of that, but it does not replace the original consent you collected — it’s an extra safety net required by U.S. carrier and CTIA rules. Typical sources of compliant consent:

Booking or Reservation Form

A signed form that explicitly authorizes SMS communication on behalf of your brand.

Web or App Opt-in

A checkout or account-creation flow with an opt-in checkbox referencing your brand and SMS messaging.

Written Agreement

A paper or e-signature agreement that lists SMS as an authorized contact channel.
If you cannot demonstrate consent for a number, do not add it to your contact list — VIVI’s middleware will block delivery and carriers can suspend the toll-free number for unsolicited messaging.

​
Create an SMS Channel

1

Open Channels

Go to Channels → Add new.
2

Set type and name

Pick SMS as the channel type and give it an appropriate name.
3

Choose country and number type

Select a Country, then pick a Number Type:

Local

A regular U.S./CA local number. Lower throughput. Available immediately with no extra verification.

Toll-free

A national toll-free number. Higher throughput. Requires Twilio compliance verification before SMS traffic can flow. Expect 1–5 business days to verify.
When you pick Toll-free, VIVI shows a notice that you’ll need to submit the toll-free verification form from the channel’s settings page once the number is created.
4

Pick a number

Optionally set an area code and/or vanity pattern, pick a phone number from the available list, then click Save.
5

Accept the SMS Channel Usage Agreement

Before VIVI provisions the number, the usage agreement appears as a modal. You must explicitly accept it for the channel to be created.The agreement codifies the obligations described in Prerequisites: the number is for transactional and customer support messages only (no marketing, promotional, or unsolicited content), end-users must have explicitly opted in before any SMS is sent, and violations can lead to the number being suspended.Click I Agree & Create Channel to continue — VIVI then provisions the number from Twilio.
6

Complete toll-free verification (toll-free only)

If you chose Toll-free, open the channel and complete the toll-free verification form. Approval normally takes 1–5 business days.
Every SMS channel ships with an automated consent layer. You configure the wording once per channel and VIVI handles the rest of the SMS conversation around it. Open the channel and switch to the Consent tab. The tab has three short templates with a live phone preview on the right. The placeholder {brand} is automatically substituted with the channel’s name at send time.
The first message VIVI sends to a brand-new recipient.It introduces your brand, asks for confirmation, and includes the mandatory STOP instruction (CTIA requirement). The actual message your agent wanted to send is held in a queue until the recipient replies with an opt-in keyword.
VIVI validates that your opt-in template includes a STOP instruction when you save the Consent tab — you cannot publish the template without one.

​
How Opt-in & Opt-out Work

When your agent (or you) trigger an outbound SMS to a number that has never opted in:
1

Opt-in prompt sent

VIVI sends the opt-in template: “Reply YES to receive messages from …”
2

Message queued

The actual message you wanted to send is queued, not delivered.
3

Recipient confirms

The user replies with an opt-in keyword: YES, Y, OK, OKAY, START, or SUBSCRIBE.
4

Queue drained

VIVI flips the recipient’s state to opted-in and delivers every message that was waiting.
5

Direct messaging enabled

From this point on, VIVI sends messages directly without re-prompting.
If the user never replies, queued messages stay queued until they eventually opt in (or are aged out by the janitor). They are never silently delivered.

​
Compliance Summary

You collect consent

Paper, web, or checkout opt-in is your responsibility before any number is added to VIVI.

VIVI double-confirms

The opt-in template is sent before any agent message lands, even if you believe consent already exists.

VIVI enforces opt-out

STOP, HELP, and START are handled automatically per CTIA rules — no custom logic required.

STOP instruction required

VIVI validates that opt-in and resubscribe templates include a STOP instruction before you can save.

Twilio verifies toll-free

A one-time brand and use-case verification is required for toll-free numbers before any SMS traffic flows.

Transactional use only

The provisioned number may only be used for transactional and customer support messages — no marketing or promotional content.

​
Troubleshooting

Open Channel → Consent state for that recipient. If the status shows WAITING_OPT_IN, the user hasn’t replied with an opt-in keyword yet. The message is queued and will be delivered once they confirm.
Two of the messages come from your carrier and from Twilio’s account-level Advanced Opt-Out. The third is VIVI’s own template. To eliminate the duplicate Twilio message, disable Advanced Opt-Out on the underlying Messaging Service in the Twilio Console.
Check the rejection reason displayed on the channel page. Correct the flagged fields and resubmit the verification form. Common rejection reasons include mismatched brand names, incomplete use-case descriptions, or missing opt-in evidence.

​
SMS Capabilities

Triggering Outbound Conversations

How to programmatically start an SMS conversation from your agent or an external system.

Campaigns → SMS

Bulk send to many recipients at once with the same consent and compliance guarantees.