Skip to main content

SMS (outbound)

The SMS tool lets your assistant send a text message in the middle of a conversation. Voice agent books an appointment — it texts the confirmation. Chat user agrees to a quote — it texts the payment link. Caller wants the deal in writing — it texts a summary. The assistant decides when to fire it based on the system prompt and the current turn; the text leaves from your own Twilio, Plivo, or Telnyx number.

This is the outbound side. If you want a conversation to happen over SMS (incoming texts trigger the assistant), see the SMS widget instead.

What you can do with this tool​

  • Send a text message from your configured phone number to any recipient phone number, with arbitrary body text.

Insighto ships three implementations of the same send_sms function — one for Twilio, one for Plivo, one for Telnyx. You pick the one matching whatever SMS provider account you already have. The function signature is identical across all three, so prompts are portable if you switch providers.

SMS tool vs SMS widget​

  • SMS tool (this page) is an outbound action. The assistant uses it during a conversation that started somewhere else — voice call, chat widget, web form. The original conversation continues where it started; the SMS is a one-off message.
  • SMS widget is an inbound channel. The entire conversation happens over SMS. Incoming messages start a session; the assistant replies via SMS; the back-and-forth lives as an SMS thread.

You can attach both to the same assistant — the widget handles inbound, the tool handles outbound messages from non-SMS channels.

Business use cases​

Appointment confirmation after a voice booking​

Voice assistant books a dentist appointment via Google Calendar. Right after the calendar event is created, the assistant calls send_sms with the date, time, address, and a cancel-by-reply instruction. The caller hangs up with a confirmation text on their phone — no email-search, no "what time did we say?" follow-up call.

A moving company's voice agent quotes a deposit, the customer agrees, the agent generates a PayPal link, and the agent immediately calls send_sms to text the link. The customer taps it from their lock screen and completes checkout without ever opening a browser tab. Conversion goes up dramatically vs "I'll email you a payment link" flows.

Post-chat follow-up​

A B2B SaaS chat widget converts a free-tier user to a paid plan during chat. End of conversation, the assistant calls send_sms with a discount code for the next renewal. The customer leaves the chat with a tangible artifact and the AE has a number to follow up against.

One-time verification codes​

Healthcare voice agent collects identifying info, then generates a 6-digit verification code, sends via send_sms, and asks the caller to read it back. The successful read-back confirms the caller actually controls the phone number.

Connecting​

Twilio​

  1. Tools & Integrations → Twilio → Add.
  2. Provide your Twilio Account SID and Auth Token (find these on the Twilio Console homepage).
  3. Pick a default phone number from the dropdown — Insighto fetches the list of numbers on your Twilio account.

Plivo​

  1. Tools & Integrations → Plivo → Add.
  2. Provide your Plivo Auth ID and Auth Token.
  3. Pick a default phone number from the dropdown.

Telnyx​

  1. Tools & Integrations → Telnyx → Add.
  2. Provide your Telnyx API key.
  3. Pick a default phone number from the dropdown.

Credentials are stored encrypted. The default sending number lives on the connection's configuration and is used whenever the assistant doesn't pass an explicit override.

Prerequisites​

  • An active account with the provider of your choice.
  • At least one SMS-capable phone number on that account.
  • For US long-code SMS: registered A2P 10DLC (Twilio) or the equivalent on Plivo/Telnyx.

Functions the assistant can call​

send_sms​

Sends an outbound SMS via the connected provider.

  • Arguments
    • to_ (string, required) — recipient phone number in E.164 format (e.g. +15551234567).
    • message (string, required) — the text body.
    • from_ (string, optional) — override the default sending number. Only useful if you have multiple numbers and want to pick per-call.
  • Returns — "SMS sent." on success, "SMS couldn't be sent" on any failure.

The function signature is identical across Twilio, Plivo, and Telnyx — only the underlying provider call differs.

Example invocation​

The assistant texts an appointment confirmation:

{
  "function": "send_sms",
  "arguments": {
    "to_": "+15551234567",
    "message": "Hi Alice, you're booked for Tuesday May 20 at 3pm with Dr. Smith. Reply CANCEL to cancel. — ABC Dental"
  }
}

Result returned to the assistant:

"SMS sent."

The assistant then tells the caller "I've sent the confirmation to your phone."

System prompt guidance​

Be specific about when to text and what to include:

You can send SMS messages using send_sms. Use it when:

  • You book an appointment — send a confirmation with the date, time, and provider name.
  • You generate a payment link — send the link with a one-line explanation.
  • The customer explicitly asks you to text them something.

Always confirm the phone number with the customer before sending. Pass the number in E.164 format with the country code and no spaces (e.g. +15551234567). Don't text marketing content unsolicited.

The "confirm before sending" rule matters — customers get upset when an assistant texts the wrong number, or worse, texts someone unrelated.

Templates and variability​

There's no built-in templating. Get consistent message format by being specific in the prompt:

Confirmation message format: "Hi [first name], you're booked for [day] at [time] with [provider]. Reply CANCEL to cancel. — ABC Practice"

The model fills in the placeholders from conversation context.

Multiple sending numbers​

Two options if you have several numbers on the same provider account:

  • Configure one default number per connection and pass from_ in the function call when you need to override.
  • Connect the same provider multiple times, each with a different default number, and label them clearly ("Twilio - Sales", "Twilio - Support"). Attach the right one to the right assistant.

The second approach is cleaner because the routing decision is "which assistant" rather than something the model has to remember.

Compliance — opt-in, opt-out, A2P 10DLC​

SMS is regulated and you're on the hook for following the rules:

  • TCPA / opt-in — In the US, you need documented consent before sending non-transactional texts. Transactional texts (confirmations, receipts, OTPs) have looser rules but consent is still best practice.
  • STOP / opt-out — Twilio, Plivo, and Telnyx all automatically intercept STOP replies and block future sends to that number at the provider level. You don't track the opt-outs manually; the provider does.
  • A2P 10DLC — US long-code SMS over any provider requires brand and use-case registration. Without it, deliverability drops and carriers may filter your messages.

Insighto doesn't enforce these for you — they're between you and your provider.

Costs​

SMS uses your provider account directly, so per-message costs flow through the provider's pricing. Insighto doesn't add a markup; you pay only for the LLM tokens that decided to send the message.

Failure modes​

  • Invalid phone format — provider rejects non-E.164 numbers. The assistant gets "SMS couldn't be sent" and usually re-asks. Always confirm the number before sending.
  • Recipient opted out — the provider silently filters the send. Insighto reports "SMS sent." but no message is delivered. Check the provider dashboard if you suspect delivery issues.
  • Credentials rotated or revoked — all sends fail. Re-paste credentials in the connection settings.
  • Carrier filtering — some carriers filter messages containing URLs unless A2P 10DLC is registered. If you see spotty delivery, check A2P registration status first.

Where to next​

  • Receive inbound SMS conversations via the SMS widget.
  • Pair with Google Calendar for booking + confirmation flows.
  • For MMS, bulk sends, or richer provider features, build a Custom tool.