> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SMS

> Send SMS messages from agents and workflows in telli

<Frame>
  <video src="https://migthzpcwvipwgioldfr.supabase.co/storage/v1/object/public/public_assets/changelog/2026-06-01-week-23/sms.mp4" width="3842" height="2160" controls muted autoPlay loop playsInline className="w-full rounded-xl" />
</Frame>

SMS lets you follow up with contacts from the same phone-number setup you use for calls. Use it when an agent needs to share a link during a conversation, or when a workflow should send an automatic follow-up after a call or contact event.

## Before you start

You need:

* A mobile SMS-capable phone number in telli. Check **Telephony** > **Phone Numbers** and look for the SMS capability badge.
* A contact with a valid phone number.
* Consent to message the recipient and a message that follows local messaging rules.

<Warning>
  SMS to US recipients is not supported right now. Sends to US phone numbers are recorded as failed.
</Warning>

If you do not have an SMS-capable mobile number, buy a mobile number from [Phone Numbers](./phone-numbers). Imported numbers, local numbers, and voice-only numbers do not support SMS.

## Send SMS from an agent

Use an agent SMS tool when the agent should send a configured message during a live call, such as a booking link, payment link, or confirmation message.

<Steps>
  <Step title="Open the agent">
    Open the agent you want to edit, then go to the agent tools section in the builder sidebar.
  </Step>

  <Step title="Add an SMS tool">
    Under **SMS**, click **Add SMS tool**.
  </Step>

  <Step title="Add a label">
    Give the message a label, such as `booking_link` or `confirmation_sms`. Labels must start with a letter or underscore and can contain letters, numbers, and underscores.
  </Step>

  <Step title="Choose the sender">
    Use **Use current phone call** when the SMS should come from the number used for the call. Select a fallback SMS-capable number in case the call number cannot send SMS. Use **Manually select number** when the message should always come from a specific number.
  </Step>

  <Step title="Write the message">
    Add the SMS body. You can insert available variables in the message so each send can include contact or call details.
  </Step>

  <Step title="Reference the tool in the prompt">
    Add the SMS tool reference to the prompt, for example `@sendSms:booking_link`, and explain when the agent should send it.
  </Step>
</Steps>

The agent can only send the SMS messages you configure. This keeps messages predictable and prevents the agent from composing arbitrary text at send time.

## Send SMS from a workflow

Use the **Send SMS** workflow action when telli should message a contact automatically.

<Steps>
  <Step title="Create or open a workflow">
    Go to **Workflows**, then create a workflow or open an existing draft.
  </Step>

  <Step title="Choose a trigger">
    Select the event that should start the workflow. SMS works especially well after **Call ended** triggers.
  </Step>

  <Step title="Add Send SMS">
    Add a **Send SMS** action block after the trigger or after a condition.
  </Step>

  <Step title="Choose the sender">
    Use the calling number with a fallback for call-based workflows, or manually select an SMS-capable number.
  </Step>

  <Step title="Check the recipient">
    The workflow sends the SMS to the contact phone number. Make sure the contact has a valid mobile number before you test or publish.
  </Step>

  <Step title="Write the message">
    Write the body and insert workflow variables when you need contact fields, call outcomes, collected data, or values from earlier blocks.
  </Step>

  <Step title="Publish and test">
    Publish the workflow, then run it manually against a recent call before enabling automatic sends.
  </Step>
</Steps>

See [Workflows](./workflows) for the full workflow publishing and run-monitoring flow.

First 20 outbound SMS are free once per account. Additional SMS cost 12 ct each.

## Review SMS activity

SMS conversations appear in **Conversations** alongside calls when SMS is enabled for your account. Open a conversation to see the message history and delivery state.

SMS also appears on the contact activity timeline, so you can review follow-ups next to the contact's calls and scheduled activity.

Common delivery states are:

| Status        | Meaning                                                                 |
| :------------ | :---------------------------------------------------------------------- |
| `queued`      | telli sent the message to the SMS provider and it is waiting to be sent |
| `sent`        | The provider accepted and sent the message                              |
| `delivered`   | The carrier reported delivery to the recipient                          |
| `undelivered` | The carrier could not deliver the message                               |
| `failed`      | The send failed before delivery                                         |

Inbound replies from known phone numbers are added to the matching SMS conversation. Replies from unknown numbers create a new contact from the sender number.

## Limitations

* SMS supports plain text messages. Do not use it for media attachments.
* US-recipient SMS is currently blocked for compliance reasons.
* SMS requires a mobile phone number bought in telli with SMS capability.
* The message body cannot be empty.